Natural Language Processing (NLP)

What is NLP?

ShipEngine's NLP (Natural Language Processing) APIs make it easy for you to extract structured shipping data — such as addresses, names, package weight and dimensions, insurance options, and more — from unstructured text.

Data often enters your system as unstructured text (for example: emails, SMS messages, support tickets, or other documents). ShipEngine's NLP APIs save you time from parsing this text and pulling the useful data within it. With the NLP API, you can simply send us the unstructured text, and we'll return the shipping-related data it contains.

ShipEngine's NLP endpoints return the parsed data in a structured format that is compatible with other ShipEngine endpoints, making it easy to perform additional requests, such as address validation, rate quotes, and shipping labels.

NLP uses machine learning to parse your information and determine which parts are important or relevant to shipping. Our machine learning models learn and improve over time, so it becomes more accurate and better at understanding different writing patterns.

What can NLP do for you?

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

What can ShipEngine's NLP endpoints understand?

ShipEngine NLP can currently recognize addresses for the following countries:

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

The table below represents the different types of entities ShipEngine's NLP is currently designed to recognize:

Entity Type
Recognized Atrributes

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")

Natural Language Processing (NLP)


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.