ShipEngine's easy-to-use REST API lets you manage all of your shipping needs without worrying about the complexities of different carrier APIs and protocols. We handle all the heavy lifting so you can focus on providing a first-class shipping experience for your customers at the best possible prices.
Each of ShipEngine's features can be used by itself or in conjunction with each other to build powerful shipping functionality into your application or service.
No matter your shipping volume, failed deliveries and address change surcharges cut into your bottom line and damage perception with customers. Our address validation services ensure your packages make it to the right place the first time. Learn how to leverage our address validation services here.
ShipEngine supports address validation for virtually every country on Earth, including the United States, Canada, Great Britain, Australia, Germany, France, Norway, Spain, Sweden, Israel, Italy, and over 160 others.
The address-recognition API makes it easy for you to extract address data from unstructured text, including the recipient name, line 1, line 2, city, postal code, and more.
Data often enters your system as unstructured text (for example: emails, SMS messages, support tickets, or other documents). ShipEngine's address-recognition API helps you extract meaningful, structured data from this unstructured text. The parsed address data is returned in the same structure that's used for other ShipEngine APIs, such as address validation, rate quotes, and shipping labels.
Note: Address recognition is currently supported for the United States, Canada, Australia, New Zealand, the United Kingdom, and Ireland.
The only required field is text, which is the text to be parsed. You can optionally also provide an address containing already-known values. For example, you may already know the recipient's name, city, and country, and only want to parse the street address into separate lines.
The unstructured text that contains address-related entities
curl -i -X PUT \
https://docs.shipstation.com/_mock/apis/shipengine/openapi/v1/addresses/recognize \
-H 'API-Key: YOUR_API_KEY_HERE' \
-H 'Content-Type: application/json' \
-d '{
"text": "Margie McMiller at 3800 North Lamar suite 200 in austin, tx. The zip code there is 78652."
}'Returns the parsed address, as well as a confidence score and a list of all the entities that were recognized in the text.
A confidence score between zero and one that indicates how certain the API is that it understood the text.
The parsed address. This address may not be complete, depending on how much information was included in the text and how confident the API is about each recognized entity.
Note: The address-recognition API does not currently perform any validation of the parsed address, so we recommend that you use the address-validation API to ensure that the address is correct.
The name of a contact person at this address. This field may be set instead of - or in addition to - the company_name field.
The phone number of a contact person at this address. The format of this phone number varies depending on the country.
If this is a business address, then the company name should be specified here.
The first line of the street address. For some addresses, this may be the only line. Other addresses may require 2 or 3 lines.
The second line of the street address. For some addresses, this line may not be needed.
The third line of the street address. For some addresses, this line may not be needed.
The state or province. For some countries (including the U.S.) only abbreviations are allowed. Other countries allow the full name or abbreviation.
A two-letter ISO 3166-1 country code
All of the entities that were recognized in the text. An "entity" is a single piece of data, such as a city, a postal code, or an address line. Each entity includes the original text and the parsed value.
The Entity type (e.g. "weight", "person", "address_line1", etc.)
A confidence score between zero and one that indicates how certain the API is that it correctly recognized this entity
The substring from the original text that was recognized as this entity
The index of the first character of this entity within the original text
The index of the last character of this entity within the original text
The normalized value of the entity.
Most entity results have a value field, which is the normalized value of the entity. For example, if the substring "john doe" was recognized as a "person" entity, then the value might be normalized to have proper capitalization (e.g. "John Doe"). Or if the substring "ft worth" was recognized as a "city" entity, then the value might be normalized to "Fort Worth".
Some entities have other information in addition to, or instead of a value. For example, a "dimensions" entity will have separate fields for length, width, height, and unit.
This response shows that the address-recognition API was able to recognize all the address entities in the text. Notice that the country_code is not populated and the address_residential_indicator is "unknown", since neither of these fields was included in the text.
{ "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": [ { … }, { … }, { … }, { … }, { … }, { … }, { … }, { … } ] }
The name of a contact person at this address. This field may be set instead of - or in addition to - the company_name field.
The phone number of a contact person at this address. The format of this phone number varies depending on the country.
If this is a business address, then the company name should be specified here.
The first line of the street address. For some addresses, this may be the only line. Other addresses may require 2 or 3 lines.
The second line of the street address. For some addresses, this line may not be needed.
The third line of the street address. For some addresses, this line may not be needed.
The state or province. For some countries (including the U.S.) only abbreviations are allowed. Other countries allow the full name or abbreviation.
A two-letter ISO 3166-1 country code
Indicates whether this is a residential address.
curl -i -X POST \
https://docs.shipstation.com/_mock/apis/shipengine/openapi/v1/addresses/validate \
-H 'API-Key: YOUR_API_KEY_HERE' \
-H 'Content-Type: application/json' \
-d '[
{
"name": "Mickey and Minnie Mouse",
"phone": "714-781-4565",
"company_name": "The Walt Disney Company",
"address_line1": "500 South Buena Vista Street",
"city_locality": "Burbank",
"state_province": "CA",
"postal_code": "91521",
"country_code": "US"
}
]'The request was a success.
The possible address validation status values
Any residential or business mailing address, anywhere in the world.
Note: Either
nameorcompany_namemust be set. Both may be specified, if relevant.
The name of a contact person at this address. This field may be set instead of - or in addition to - the company_name field.
The phone number of a contact person at this address. The format of this phone number varies depending on the country.
If this is a business address, then the company name should be specified here.
The first line of the street address. For some addresses, this may be the only line. Other addresses may require 2 or 3 lines.
The second line of the street address. For some addresses, this line may not be needed.
The third line of the street address. For some addresses, this line may not be needed.
The name of the city or locality
The state or province. For some countries (including the U.S.) only abbreviations are allowed. Other countries allow the full name or abbreviation.
A two-letter ISO 3166-1 country code
Any residential or business mailing address, anywhere in the world.
Note: Either
nameorcompany_namemust be set. Both may be specified, if relevant.
The name of a contact person at this address. This field may be set instead of - or in addition to - the company_name field.
The phone number of a contact person at this address. The format of this phone number varies depending on the country.
If this is a business address, then the company name should be specified here.
The first line of the street address. For some addresses, this may be the only line. Other addresses may require 2 or 3 lines.
The second line of the street address. For some addresses, this line may not be needed.
The third line of the street address. For some addresses, this line may not be needed.
The name of the city or locality
The state or province. For some countries (including the U.S.) only abbreviations are allowed. Other countries allow the full name or abbreviation.
A two-letter ISO 3166-1 country code
The list of messages that were generated during the address validation request.
The error codes that can be returned by the address validation API
Message explaining the address validation error
The different types of messages that can be returned by the address validation API
The detailed error codes that can be returned by the address validation API
A response for a verified status call.
[ { "status": "verified", "original_address": { … }, "matched_address": { … }, "messages": [] } ]
Webhooks are a powerful feature of ShipEngine that can save you from sending repeated polling requests to check on the state of something. With webhooks, ShipEngine will automatically contact your servers when the state changes. This can include parcel tracking events, notification of the completion of a batch operation, or new sales orders.