Parse Shipping Info from Text

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 have a 4oz package that's 5x10x14in, and I need to ship it to Margie McMiller at 3800 North Lamar suite 200 in austin, tx 78652. Please send it via USPS first class and require an adult signature. It also needs to be insured for $400.

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

Entity Type Value
weight 4 ounces
dimensions 5 inch x 10 inch x 14 inch
address Margie McMiller
3800 North Lamar
Suite 200
Austin, TX 78652
person Margie McMiller
carrier stamps.com
service USPS First Class Mail
delivery_confirmation Adult Signature
insured_value 400 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.90313... which indicates a 90.3% 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

curl -iX POST https://api.shipengine.com/v1/shipments/recognize \
-H 'Content-Type: application/json' \
-H 'API-Key: __YOUR_API_KEY_HERE__' \
-d '
{
  "text": "I have a 4oz package that's 5x10x14in, and I need to ship it to Margie McMiller at 3800 North Lamar suite 200 in austin, tx 78652.  Please send it via USPS first class and require an adult signature.  It also needs to be insured for $400."
}'

Example Response

{
  "score": 0.9031369611169101,
  "shipment": {
    "carrier_id": "se-118608",
    "service_code": "usps_first_class_mail",
    "confirmation": "adult_signature",
    "ship_to": {
      "name": "Margie McMiller",
      "company_name": "Adult Signature",
      "address_line1": "3800 North Lamar",
      "address_line2": "Suite 200",
      "city_locality": "Austin",
      "state_province": "TX",
      "postal_code": "78652",
      "address_residential_indicator": "unknown"
    },
    "packages": [
      {
        "weight": {
          "value": 4,
          "unit": "ounce"
        },
        "dimensions": {
          "length": 5,
          "width": 10,
          "height": 14,
          "unit": "inch"
        },
        "insured_value": {
          "amount": 400,
          "currency": "USD"
        }
      }
    ]
  },
  "entities": [
    {
      "type": "weight",
      "score": 0.9805313966503588,
      "text": "4oz",
      "start_index": 9,
      "end_index": 11,
      "result": {
        "value": 4,
        "unit": "ounce"
      }
    },
    {
      "type": "dimensions",
      "score": 1,
      "text": "5x10x14in",
      "start_index": 28,
      "end_index": 36,
      "result": {
        "length": 5,
        "width": 10,
        "height": 14,
        "unit": "inch"
      }
    },
    {
      "type": "dimension",
      "score": 0.9805313966503588,
      "text": "14in",
      "start_index": 33,
      "end_index": 36,
      "result": {
        "unit": "inch",
        "value": 14
      }
    },
    {
      "type": "address",
      "score": 0.9281558837267101,
      "text": "to Margie McMiller at 3800 North Lamar suite 200 in austin, tx 78652. Please send it via USPS first class and require an adult signature",
      "start_index": 61,
      "end_index": 196,
      "result": {
        "direction": "to",
        "name": "Margie McMiller",
        "company_name": "Adult Signature",
        "address_line1": "3800 North Lamar",
        "address_line2": "Suite 200",
        "city_locality": "Austin",
        "state_province": "TX",
        "postal_code": "78652"
      }
    },
    {
      "type": "person",
      "score": 0.9519646137063122,
      "text": "Margie McMiller",
      "start_index": 64,
      "end_index": 78,
      "result": {
        "value": "Margie McMiller"
      }
    },
    {
      "type": "address_line",
      "score": 0.9805313966503588,
      "text": "3800 North Lamar",
      "start_index": 83,
      "end_index": 98,
      "result": {
        "line": 1,
        "value": "3800 North Lamar"
      }
    },
    {
      "type": "number",
      "score": 0.9805313966503588,
      "text": "3800",
      "start_index": 83,
      "end_index": 86,
      "result": {
        "type": "cardinal",
        "value": 3800
      }
    },
    {
      "type": "address_line",
      "score": 1,
      "text": "suite 200",
      "start_index": 100,
      "end_index": 108,
      "result": {
        "line": 2,
        "value": "Suite 200"
      }
    },
    {
      "type": "dimension",
      "score": 0.4792571878834418,
      "text": "200 in",
      "start_index": 106,
      "end_index": 111,
      "result": {
        "unit": "inch",
        "value": 200
      }
    },
    {
      "type": "city_locality",
      "score": 0.9805313966503588,
      "text": "austin",
      "start_index": 113,
      "end_index": 118,
      "result": {
        "value": "Austin"
      }
    },
    {
      "type": "state_province",
      "score": 0.6082904353940255,
      "text": "tx",
      "start_index": 121,
      "end_index": 122,
      "result": {
        "name": "Texas",
        "value": "TX"
      }
    },
    {
      "type": "postal_code",
      "score": 0.9519646137063122,
      "text": "78652",
      "start_index": 124,
      "end_index": 128,
      "result": {
        "value": "78652"
      }
    },
    {
      "type": "carrier",
      "score": 0.9519646137063122,
      "text": "USPS",
      "start_index": 150,
      "end_index": 153,
      "result": {
        "name": "Stamps.com",
        "value": "se-118608"
      }
    },
    {
      "type": "service",
      "score": 0.6082904353940255,
      "text": "first class",
      "start_index": 155,
      "end_index": 165,
      "result": {
        "name": "USPS First Class Mail",
        "value": "usps_first_class_mail"
      }
    },
    {
      "type": "number",
      "score": 0.9805313966503588,
      "text": "first",
      "start_index": 155,
      "end_index": 159,
      "result": {
        "type": "ordinal",
        "value": 1
      }
    },
    {
      "type": "company",
      "score": 0.9519646137063122,
      "text": "adult signature",
      "start_index": 182,
      "end_index": 196,
      "result": {
        "value": "Adult Signature"
      }
    },
    {
      "type": "delivery_confirmation",
      "score": 0.8530163983409642,
      "text": "adult signature",
      "start_index": 182,
      "end_index": 196,
      "result": {
        "name": "Adult Signature",
        "value": "adult_signature"
      }
    },
    {
      "type": "insurance",
      "score": 0.8530163983409642,
      "text": "insured for $400",
      "start_index": 219,
      "end_index": 234,
      "result": {
        "value": 400,
        "unit": "USD"
      }
    },
    {
      "type": "insured_value",
      "score": 1,
      "text": "$400",
      "start_index": 231,
      "end_index": 234,
      "result": {
        "unit": "USD",
        "value": 400
      }
    }
  ]
}

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
curl -iX PUT https://api.shipengine.com/v1/shipments/recognize \
-H 'Content-Type: application/json' \
-H 'API-Key: __YOUR_API_KEY_HERE__' \
-d '{
    "text": "I have a 4oz package that's 5x10x14in, and I need to ship it to Margie McMiller at 3800 North Lamar suite 200 in austin, tx 78652. Please send it via USPS first class and require an adult signature. It also needs to be insured for $400.",
    "shipment": {
      "ship_from": {
        "company_name": "My Warehouse",
        "phone": "555-555-5555",
        "address_line1": "587 Shotwell St.",
        "address_line2": "Suite 201",
        "city_locality": "San Francisco",
        "state_province": "CA",
        "postal_code": "94110",
        "country_code": "US",
        "address_residential_indicator": "yes"
      }
    }
  }
'

Entity Types

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

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: "3800 N. Lamar 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 ("shipsurance", "carrier", or "external")
insurance_provider name: string (ex: "Shipsurance", "Carrier Insurance")
value: enumerated string ("shipsurance", "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")