Shipment Recognition
ShipStation API can use machine learning and natural language processing (NLP) to parse shipment data from unstructured text with the /v1/shipments/recognize endpoint. Shipment recognition works in a similar way as our /v1/addresses/recognize endpoint, but can parse shipment details in addition to address details.
Data often enters your system as unstructured text (as with emails, SMS messages, support tickets, or other documents). Our shipment recognition endpoint saves you from parsing this text manually 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 model learns and improves over time, so it will become more accurate and better at understanding different writing patterns.
Example Use Case
Let's say you receive an order via email. You can send the text of the email in your request and we'll automatically detect the shipment information, such as the customer's address, delivery confirmation preferences, and insurance needs.
Here's an example of unstructured text from an email:
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.
When you send this text to ShipStation API via the /v1/shipments/recognize endpoint, it will recognize the following pieces of information:
| Property | Value |
|---|---|
weight | 17 lbs |
dimensions | 36 inch x 12 inch x 24 inch |
address | Amanda Miller 525 Winchester Blvd San Jose, CA 95128 |
person | Amanda Miller |
delivery_confirmation | Adult Signature |
insured_value | 400 USD |
Requirements
- The unstructured text goes into the
textproperty as a string in the request body. - ShipStation API NLP currently supports English text and can recognize addresses for the following countries:
- Australia
- Canada
- Ireland
- New Zealand
- United Kingdom
- United States
Adding a Shipment Object
You can specify any already-known shipment properties in a shipment object in the request body. This can help you automatically define your known variable such as:
ship_fromcarrier_idconfirmationpackage dimensionsverify_address
Entity Types
The response includes an entities array, which breaks down the separate pieces that the NLP model parsed from the unstructured text. Each type of information is called an "entity". For example, an address, a city, and a phone number would all be individual entities. Additionally, entities can have one or more attributes.
The shipment recognition endpoint is currently designed to recognize the following types of entities and the associated attributes:
| Entity Type | Recognized Attributes |
|---|---|
address | direction: 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_line | line: number (usually 1, 2 or 3) value: string (ex: "525 Winchester Blvd") |
carrier | name: string (ex: "FedEx", "UPS", "Stamps.com") value: string (ex: "fedex", "ups", "stamps_com") |
city_locality | value: string |
company | value: string |
delivery_confirmation | name: string (ex: "Adult Signature") value: string (ex: "adult_signature") |
country | name: string value: string |
dimension | value: number unit: enumerated string ( inch or centimeter) dimension: enumerated string ( length, width, or height) |
dimensions | length: number width: number height: number unit: enumerated string ( inch, or centimeter") |
insurance | value: number unit: enumerated string ( USD, CAD, AUD, GBP, or EUR) provider: enumerated string ( parcelguard, carrier, or external) |
insurance_provider | name: string (ex: "Parcelguard", "Carrier Insurance") value: enumerated string ( parcelguard, carrier, or external) |
insured_value | value: number unit: enumerated string ( USD, CAD, AUD, GBP, or EUR) |
monetary_value | value: number unit: enumerated string ( USD, CAD, AUD, GBP, or EUR) |
number | type: enumerated string (cardial, ordinal, or percentage) value: number |
person | value: string |
phone_number | value: string |
postal_code | value: string |
residential_indicator | value: enumerated string (yes, no, or unknown) |
service | name: string (ex: "USPS First Class Mail Intl") value: string (ex: "usps_first_vlass_mail_international") |
state_province | name: string (ex: "Texas", "Quebec", "New South Wales") value: string (ex: "TX", "QC", "NSW") country: string (ex: "US", "CA", "AU") |
timeframe | type: 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. |
weight | value: number unit: enumerated string ( pound, ounce, gram, or kilogram) |
Example Request & Response
We'll use the example use case from above in our example request with a shipment object that defines our ship_from address.
PUT /v1/shipments/recognize
Example Response
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 you need any additional input or verification from your user.
The entities array breaks down the recognized data further into their own individual objects with the attributes as properties, the result, and the confidence score for each entity.