shipengine-logo

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.

IMPORTANT: Endpoint is in Beta

This 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

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:

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.

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

Entity TypeValue
personAmanda Miller
addressAmanda Miller
525 Winchester Blvd
San Jose, CA 95128
address_residential_indicatorresidential
address_line1525 Winchester Blvd
city_localitySan Jose
state_provinceCA
postal_code95128

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.971069... which indicates a 97% 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

1
2
3
4
5
6
7
8
POST /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."
}

Example Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
{
    "score": 0.9710697187242877,
    "address": {
        "name": "Amanda Miller",
        "address_line1": "525 Winchester Blvd",
        "city_locality": "San Jose",
        "state_province": "CA",
        "postal_code": "95128",
        "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"
            }
        }
    ]
}

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
  • city_locality
  • state_province
  • postal_code
  • country_code
1
2
3
4
5
6
7
8
9
10
11
12
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"
  }
}


Entity Types

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

Entity TypeRecognized Attributes
addressdirection: 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_lineline: number(usually 1, 2 or 3)
value: string (ex: "525 Winchester Blvd")
city_localityvalue: string
countryname: string
value: string
numbertype: enumerated string ("cardial", "ordinal", "or "percentage")
value: number
personvalue: string
phone_numbervalue: string
postal_codevalue: string
residential_indicatorvalue: enumerated string ("yes", "no", or "unknown")
state_provincename: string (ex: "Texas", "Quebec", "New South Wales")
value: string (ex: "TX", "QC", "NSW")
country: string (ex: "US", "CA", "AU")