# 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](/apis/shipengine/docs/addresses/parse), 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 `text` property 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_from`
* `carrier_id`
* `confirmation`
* `package dimensions`
* `verify_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**


```http
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"
    }
  }
}
```

**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.


```json
{
    "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"
        },
        "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"
        },
        "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"
            }
        }
    ]
}
```