Parse an Address
ShipEngine uses machine learning and natural language processing (NLP) to parse addresses data from unstructured text.
Data often enters your system as unstructured text (for example: emails, SMS messages, support tickets, or other documents). ShipEngine's address 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 whatever address data it contains.
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 extract the customer's address. Here's an example:
Please send it to Margie McMiller's office at 3800 North Lamar suite 200 in austin, tx. The zip code there is 78652.
You could send this text to ShipEngine via the PUT /v1/addresses/recognize endpoint, and it will recognize the following pieces of information:
| Entity Type | Value |
|---|---|
person |
Margie McMiller |
address |
Margie McMiller 3800 North Lamar Suite 200 Austin, TX 78652 |
address_residential_indicator |
non-residential |
address_line1 |
3800 North Lamar |
address_line2 |
Suite 200 |
city_locality |
Austin |
state_province |
Texas |
postal_code |
78652 |
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.912... which indicates a 91.2% 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/addresses/recognize \
-H 'Content-Type: application/json' \
-H 'API-Key: __YOUR_API_KEY_HERE__' \
-d '{
"text": "Margie McMiller at 3800 North Lamar suite 200 in austin, tx. The zip code there is 78652."
}'
Example Response
{
"score": 0.9122137426845613,
"address": {
"name": "Margie McMiller",
"address_line1": "3800 North Lamar",
"address_line2": "Suite 200",
"city_locality": "Austin",
"state_province": "TX",
"postal_code": "78652",
"address_residential_indicator": "unknown"
},
"entities": [
{
"type": "person",
"score": 0.9519646137063122,
"text": "Margie McMiller",
"start_index": 0,
"end_index": 14,
"result": {
"value": "Margie McMiller"
}
},
{
"type": "address_line",
"score": 0.9805313966503588,
"text": "3800 North Lamar",
"start_index": 19,
"end_index": 34,
"result": {
"line": 1,
"value": "3800 North Lamar"
}
},
{
"type": "number",
"score": 0.9805313966503588,
"text": "3800",
"start_index": 19,
"end_index": 22,
"result": {
"type": "cardinal",
"value": 3800
}
},
{
"type": "address_line",
"score": 1,
"text": "suite 200",
"start_index": 36,
"end_index": 44,
"result": {
"line": 2,
"value": "Suite 200"
}
},
{
"type": "number",
"score": 0.9805313966503588,
"text": "200",
"start_index": 42,
"end_index": 44,
"result": {
"type": "cardinal",
"value": 200
}
},
{
"type": "city_locality",
"score": 0.9805313966503588,
"text": "austin",
"start_index": 49,
"end_index": 54,
"result": {
"value": "Austin"
}
},
{
"type": "state_province",
"score": 0.6082904353940255,
"text": "tx",
"start_index": 57,
"end_index": 58,
"result": {
"name": "Texas",
"value": "TX"
}
},
{
"type": "postal_code",
"score": 0.9519646137063122,
"text": "78652",
"start_index": 84,
"end_index": 88,
"result": {
"value": "78652"
}
}
]
}
tip
The address object can be used in other endpoints as-is
The attributes defined in the address object are structured in the same fashion as the "ship_from" and "ship_to" objects.
Already-known fields
You can specify any already-known fields for your address object in the request. This can help you automatically define any known variables you might collect such as...
- name set* city_locality
- state_province
- postal_code
- country_code
curl -iX PUT https://api.shipengine.com/v1/addresses/recognize \
-H 'Content-Type: application/json' \
-H 'API-Key: __YOUR_API_KEY_HERE__' \
-d '{
"text": "Margie McMiller at 3800 North Lamar suite 200 in austin, tx. The zip code there is 78652.",
"address": {
"name": "Margaret McMiller",
"country_code": "US"
}
}
'
Entity Types
The address 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") |
| 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") |