# Address Recognition

ShipStation API can use machine learning and natural language processing (NLP) to parse addresses data from unstructured text using the `/v1/addresses/recognize` endpoint.

Data can often enter your system as unstructured text (as with emails, SMS messages, support tickets, or other documents). The address recognition endpoint saves you from parsing this text manually and trying to extract the useful data within it. Instead, you can send us the unstructured text and we'll return whatever address data it contains.

Our machine learning model learns and improves over time so it becomes more accurate and better at understanding different writing patterns.

> **IMPORTANT:**
### Endpoint is in Beta
The address recognition endpoint is experimental and, at this moment, not fully supported. Please understand the current capabilities for this endpoint are limited and you should not expect full functionality.


## Example Use Case

Let's say you receive an order via email. You can send the text of the email to ShipStation API and it will automatically extract the customer's address.

Here's an example of unstructured text from an email:

> I need to send a package to my friend Amanda Miller’s house at 525 Winchester Blvd in San Jose (that's california, obviously). The zip code there is 95128.


When you submit this to the `/v1/addresses/recognize` endpoint, it will recognize the following pieces of information:

| Property | Value |
|  --- | --- |
| `person` | Amanda Miller |
| `address` | Amanda Miller  525 Winchester Blvd  San Jose, CA 95128 |
| `address_residential_indicator` | residential |
| `address_line1` | 525 Winchester Blvd |
| `city_locality` | San Jose |
| `state_province` | CA |
| `postal_code` | 95128 |


For more complex parsing that includes other types of shipment data beyond just the address, see our [Shipment Recognition page](/apis/shipengine/docs/shipping/shipment-recognition).

## Requirements

* This endpoint is only available to accounts on the [Advanced plan or higher](https://help.shipengine.com/hc/en-us/articles/19326509952027).
* The unstructured text goes into the `text` property as a *string* in the request body.
* Our NLP currently supports English text and can recognize addresses for the following countries:
  * Australia
  * Canada
  * Ireland
  * New Zealand
  * United Kingdom
  * United States


## Already-Known Properties

You can specify any already-known properties for your address in the request. This can help you automatically define any known variables you might collect, such as:

* `name`
* `city_locality`
* `state_province`
* `postal_code`
* `country_code`


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

Our address recognition can currently 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") |
| `city_locality` | **value:** *string* |
| `country` | **name:** *string*  **value:** *string* |
| `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`) |
| `state_province` | **name:** *string* (ex: "Texas", "Quebec", "New South Wales")  **value:** *string* (ex: "TX", "QC", "NSW")  **country:** *string* (ex: "US", "CA", "AU") |


## Example Request & Response

We'll use the example use case from above in our example request, with the additional known properties for `name` and `country_code`.

**PUT  /v1/addresses/recognize**


```http
PUT /v1/addresses/recognize HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json

{
  "text": "I need to send a package to my friend Amanda Millers house at 525 Winchester Blvd in San Jose (thats california, obviously). The zip code there is 95128.",
  "address": {
    "name": "Dr. Amanda L Miller",
    "country_code": "US"
  }
}
```

**Example Response**

The response includes a `score` property with a decimal number to indicate level of confidence in the parsing accuracy. In this example, the response has an overall score of 0.971069... which indicates a 97% confidence that it parsed the text correctly. The score value can help your application programmatically decide if you will 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.9710697187242877,
    "address": {
        "name": "Dr. Amanda Miller",
        "address_line1": "525 Winchester Blvd",
        "city_locality": "San Jose",
        "state_province": "CA",
        "postal_code": "95128",
        "country_code": "US",
        "address_residential_indicator": "yes"
    },
    "entities": [
        {
            "type": "person",
            "score": 0.9519646137063122,
            "text": "Amanda Miller",
            "start_index": 38,
            "end_index": 50,
            "result": {
                "value": "Amanda Miller"
            }
        },
        {
            "type": "residential_indicator",
            "score": 0.9519646137063122,
            "text": "house",
            "start_index": 54,
            "end_index": 58,
            "result": {
                "value": "yes"
            }
        },
        {
            "type": "address_line",
            "score": 0.9805313966503588,
            "text": "525 Winchester Blvd",
            "start_index": 63,
            "end_index": 81,
            "result": {
                "line": 1,
                "value": "525 Winchester Blvd"
            }
        },
        {
            "type": "number",
            "score": 0.9805313966503588,
            "text": "525",
            "start_index": 63,
            "end_index": 65,
            "result": {
                "type": "cardinal",
                "value": 525
            }
        },
        {
            "type": "city_locality",
            "score": 0.9805313966503588,
            "text": "San Jose",
            "start_index": 86,
            "end_index": 93,
            "result": {
                "value": "San Jose"
            }
        },
        {
            "type": "state_province",
            "score": 0.9805313966503588,
            "text": "california",
            "start_index": 103,
            "end_index": 112,
            "result": {
                "name": "California",
                "value": "CA"
            }
        },
        {
            "type": "postal_code",
            "score": 0.9519646137063122,
            "text": "95128",
            "start_index": 149,
            "end_index": 153,
            "result": {
                "value": "95128"
            }
        }
    ]
}
```

> **TIP:**
### Use the Address Object in Other Endpoints
The properties defined in the address object are structured in the same way as the `ship_from` and `ship_to` objects. You can use the address object returned from this endpoint in other requests that require an address object.