Site Logo

Shipment Recognition

ShipEngine uses machine learning and natural language processing (NLP) to parse shipping data from unstructured text.

Data often enters your system as unstructured text (for example: emails, SMS messages, support tickets, or other documents). ShipEngine's shipment recognition API saves you from parsing this text and trying to extract the useful data within it. Instead, you can simply send us the unstructured text, and we'll return any shipping data it contains — such as addresses, names, package weight and dimensions, insurance options, and more

Our machine learning models learn and improve over time, so they become more accurate and better at understanding different writing patterns.

Example

Let's say you receive an order via email. You can send the text of the email to ShipEngine and it will automatically detect the shipment information, such as the customer's address, delivery confirmation preferences, and insurance needs. Here's an example:

I need to ship a 17lb package that’s 36x12x24in. It’s going to Amanda Miller’s house at 525 Winchester Blvd in San Jose California. The zip code is 95128. It's really valuable, so insure it for $400 and require an adult signature please.

You could send this text to ShipEngine via the PUT /v1/shipments/recognize endpoint, and it will recognize the following pieces of information:

Entity TypeValue
weight17 lbs
dimensions36 inch x 12 inch x 24 inch
addressAmanda Miller
525 Winchester Blvd
San Jose, CA 95128
personAmanda Miller
delivery_confirmationAdult Signature
insured_value400 USD

Supported Countries

ShipEngine NLP currently supports English text, and can recognize addresses for the following countries:

  • Australia
  • Canada
  • Ireland
  • New Zealand
  • United Kingdom
  • United States

API Sample

In the API sample below, the response has an overall score of 0.96044... which indicates a 96% confidence that it parsed the text correctly. The score value can help your application programmatically decide if any additional input or verification from your user is needed.

The entities array breaks down the recognized data further into their own individual objects and provides additional scoring on the confidence for each field.

Example Request

1
2
3
4
5
6
7
8
POST /v1/shipments/recognize HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json
{
"text": "I need to ship a 17lb package thats 36x12x24in. Its going to Amanda Millers house at 525 Winchester Blvd in San Jose California. The zip code is 95128. Its really valuable, so insure it for $400 and require an adult signature please."
}

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
{
"score": 0.9604458751176728,
"shipment": {
"confirmation": "adult_signature",
"ship_to": {
"name": "Amanda Miller",
"company_name": "Adult Signature",
"address_line1": "525 Winchester Blvd",
"city_locality": "San Jose",
"state_province": "CA",
"postal_code": "95128",
"address_residential_indicator": "yes"
},
"packages": [
{
"weight": {
"value": 17,
"unit": "pound"
},
"dimensions": {
"length": 36,
"width": 12,
"height": 24,
"unit": "inch"
},
"insured_value": {
"amount": 400,
"currency": "USD"
}
}
]
},
"entities": [
{
"type": "weight",
"score": 0.9805313966503588,
"text": "17lb",
"start_index": 17,
"end_index": 20,
"result": {
"value": 17,
"unit": "pound"
}
},
{
"type": "dimensions",
"score": 1,
"text": "36x12x24in",
"start_index": 37,
"end_index": 46,
"result": {
"length": 36,
"width": 12,
"height": 24,
"unit": "inch"
}
},
{
"type": "dimension",
"score": 0.9805313966503588,
"text": "24in",
"start_index": 43,
"end_index": 46,
"result": {
"unit": "inch",
"value": 24
}
},
{
"type": "address",
"score": 0.9686815805970408,
"text": "to Amanda Miller’s house at 525 Winchester Blvd in San Jose California. The zip code is 95128. It's really valuable, so insure it for $400 and require an adult signature",
"start_index": 60,
"end_index": 228,
"result": {
"direction": "to",
"name": "Amanda Miller",
"company_name": "Adult Signature",
"address_line1": "525 Winchester Blvd",
"city_locality": "San Jose",
"state_province": "CA",
"postal_code": "95128",
"address_residential_indicator": "yes"
}
},
{
"type": "person",
"score": 0.9519646137063122,
"text": "Amanda Miller",
"start_index": 63,
"end_index": 75,
"result": {
"value": "Amanda Miller"
}
},
{
"type": "residential_indicator",
"score": 0.9519646137063122,
"text": "house",
"start_index": 79,
"end_index": 83,
"result": {
"value": "yes"
}
},
{
"type": "address_line",
"score": 0.9805313966503588,
"text": "525 Winchester Blvd",
"start_index": 88,
"end_index": 106,
"result": {
"line": 1,
"value": "525 Winchester Blvd"
}
},
{
"type": "number",
"score": 0.9805313966503588,
"text": "525",
"start_index": 88,
"end_index": 90,
"result": {
"type": "cardinal",
"value": 525
}
},
{
"type": "city_locality",
"score": 0.9805313966503588,
"text": "San Jose",
"start_index": 111,
"end_index": 118,
"result": {
"value": "San Jose"
}
},
{
"type": "state_province",
"score": 0.9805313966503588,
"text": "California",
"start_index": 120,
"end_index": 129,
"result": {
"name": "California",
"value": "CA"
}
},
{
"type": "postal_code",
"score": 0.9519646137063122,
"text": "95128",
"start_index": 148,
"end_index": 152,
"result": {
"value": "95128"
}
},
{
"type": "insurance",
"score": 0.8530163983409642,
"text": "insure it for $400",
"start_index": 180,
"end_index": 197,
"result": {
"value": 400,
"unit": "USD"
}
},
{
"type": "insured_value",
"score": 1,
"text": "$400",
"start_index": 194,
"end_index": 197,
"result": {
"unit": "USD",
"value": 400
}
},
{
"type": "company",
"score": 0.9519646137063122,
"text": "adult signature",
"start_index": 214,
"end_index": 228,
"result": {
"value": "Adult Signature"
}
},
{
"type": "delivery_confirmation",
"score": 0.8530163983409642,
"text": "adult signature",
"start_index": 214,
"end_index": 228,
"result": {
"name": "Adult Signature",
"value": "adult_signature"
}
}
]
}

Already-known fields

You can specify any already-known fields for your shipment in the request. This can help you automatically define your known variable such as...

  • ship_from
  • carrier_id
  • confirmation
  • package dimensions
  • verify_address
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
PUT /v1/shipments/recognize HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json
{
"text": "I need to ship a 17lb package thats 36x12x24in. Its going to Amanda Millers house at 525 Winchester Blvd in San Jose California. The zip code is 95128. Its really valuable, so insure it for $400 and require an adult signature please.",
"shipment": {
"ship_from": {
"company_name": "Example Corp.",
"name": "John Doe",
"phone": "111-111-1111",
"address_line1": "4009 Marathon Blvd",
"address_line2": "Suite 300",
"city_locality": "Austin",
"state_province": "TX",
"postal_code": "78756",
"country_code": "US",
"address_residential_indicator": "no"
}
}
}

Entity Types

The shipment recognition API is currently designed to recognize the following types of entities:

Entity TypeRecognized Attributes
addressdirection: enumerated string ("from" or "to")
name: string
company_name: string
phone: string
address_line1: string
address_line2: string
address_line3: string
city_locality: string
state_province: string
postal_code: string
country_code: string
address_residential_indicator: enumerated string ("yes", "no", or "unknown")
address_lineline: number(usually 1, 2 or 3)
value: string (ex: "525 Winchester Blvd")
carriername: string (ex: "FedEx", "UPS", "Stamps.com")
value: string (ex: "fedex", "ups", "stamps_com")
city_localityvalue: string
companyvalue: string
delivery_confirmationname: string (ex: "Adult Signature")
value: string (ex: "adult_signature")
countryname: string
value: string
dimensionvalue: number
unit: enumerated string ("inch" or "centimeter")
dimension: enumerated string ("length", "width", or "height")
dimensionslength: number
width: number
height: number
unit: enumerated string ("inch", or "centimeter")
insurancevalue: number
unit: enumerated string ("USD", "CAD", "AUD", "GBP", or "EUR")
provider: enumerated string ("shipsurance", "carrier", or "external")
insurance_providername: string (ex: "Shipsurance", "Carrier Insurance")
value: enumerated string ("shipsurance", "carrier", or "external")
insured_valuevalue: number
unit: enumerated string ("USD", "CAD", "AUD", "GBP", or "EUR")
monetary_valuevalue: number
unit: enumerated string ("USD", "CAD", "AUD", "GBP", or "EUR")
numbertype: enumerated string ("cardial", "ordinal", "or "percentage")
value: number
personvalue: string
phone_numbervalue: string
postal_codevalue: string
residential_indicatorvalue: enumerated string ("yes", "no", or "unknown")
servicename: string (ex: "USPS First Class Mail Intl")
value: string (ex: "usps_first_vlass_mail_international")
state_provincename: string (ex: "Texas", "Quebec", "New South Wales")
value: string (ex: "TX", "QC", "NSW")
country: string (ex: "US", "CA", "AU")
timeframetype: enumerated string ("date" or "range")
If the type is "date"
value: string (ex: "2018-11-07T08:30:00.000Z")
if the type is "range"
start: string (ex: "2018-11-07T08:30:00.000Z")
end: string (ex: "2018-11-07T08:30:00.000Z")
NOTE: Timezones are not currently supported. All dates and times are returned in UTC
weightvalue: number
unit: enumerated string ("pound", "ounce", "gram", or "kilogram")