---
title: "Parse an address"
method: PUT
path: "/v1/addresses/recognize"
tags: ["addresses"]
---

# Parse an address

`PUT /v1/addresses/recognize`

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.

## Request body

- ParseAddressRequestBody — 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.
  - `text` string, required — The unstructured text that contains address-related entities
  - `address` PartialAddress — A complete or partial mailing address.
    - `name` string — The name of a contact person at this address. This field may be set instead of - or in addition to - the `company_name` field.
    - `phone` string — The phone number of a contact person at this address. The format of this phone number varies depending on the country.
    - `email` string, nullable — Email for the address owner.
    - `company_name` string, nullable — If this is a business address, then the company name should be specified here.
    - `address_line1` string — The first line of the street address. For some addresses, this may be the only line. Other addresses may require 2 or 3 lines.
    - `address_line2` string, nullable — The second line of the street address. For some addresses, this line may not be needed.
    - `address_line3` string, nullable — The third line of the street address. For some addresses, this line may not be needed.
    - `city_locality` string — The name of the city or locality
    - `state_province` string — The state or province. For some countries (including the U.S.) only abbreviations are allowed. Other countries allow the full name or abbreviation.
    - `postal_code` string — postal code
    - `country_code` string — A two-letter [ISO 3166-1 country code](https://en.wikipedia.org/wiki/ISO_3166-1)
    - `address_residential_indicator` 'unknown' | 'yes' | 'no' — Indicates whether an address is residential.

## Response `200`

Returns the parsed address, as well as a confidence score and a list of all the entities that were recognized in the text.

- ParseAddressResponseBody — The parsed address, as well as a confidence score and a list of all the entities that were recognized in the text.
  - `score` number, double, required — A confidence score between zero and one that indicates how certain the API is that it understood the text.
  - `address` PartialAddress, required — A complete or partial mailing address.
    - `name` string — The name of a contact person at this address. This field may be set instead of - or in addition to - the `company_name` field.
    - `phone` string — The phone number of a contact person at this address. The format of this phone number varies depending on the country.
    - `email` string, nullable — Email for the address owner.
    - `company_name` string, nullable — If this is a business address, then the company name should be specified here.
    - `address_line1` string — The first line of the street address. For some addresses, this may be the only line. Other addresses may require 2 or 3 lines.
    - `address_line2` string, nullable — The second line of the street address. For some addresses, this line may not be needed.
    - `address_line3` string, nullable — The third line of the street address. For some addresses, this line may not be needed.
    - `city_locality` string — The name of the city or locality
    - `state_province` string — The state or province. For some countries (including the U.S.) only abbreviations are allowed. Other countries allow the full name or abbreviation.
    - `postal_code` string — postal code
    - `country_code` string — A two-letter [ISO 3166-1 country code](https://en.wikipedia.org/wiki/ISO_3166-1)
    - `address_residential_indicator` 'unknown' | 'yes' | 'no' — Indicates whether an address is residential.
  - `entities` RecognizedEntity[], required — 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.
    - `type` string, required — The Entity type (e.g. "weight", "person", "address_line1", etc.)
    - `score` number, double, required — A confidence score between zero and one that indicates how certain the API is that it correctly recognized this entity
    - `text` string, required — The substring from the original text that was recognized as this entity
    - `start_index` integer, required — The index of the first character of this entity within the original text
    - `end_index` integer, required — The index of the last character of this entity within the original text
    - `result` NormalizedEntity — 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`.

## Other responses

- `400` — The request contained errors.
- `500` — An error occurred on ShipEngine's side. > This error will automatically be reported to our engineers.

---

[API](https://skmtc.net/shipengine/apis/shipengine-api.md) · [All operations](https://skmtc.net/shipengine/apis/shipengine-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/shipengine/shipengine-api/revisions/6af91511d87e/schema)