# Parse an address

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.

Endpoint: PUT /v1/addresses/recognize
Version: 1.1.202604070904
Security: api_key

## Request fields (application/json):

  - `text` (string, required)
    The unstructured text that contains address-related entities
    Example: "Margie McMiller at 3800 North Lamar suite 200 in austin, tx.  The zip code there is 78652."

  - `address` (object)
    You can optionally provide any already-known address 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.

  - `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.
    Example: "John Doe"

  - `address.phone` (string)
    The phone number of a contact person at this address.  The format of this phone number varies depending on the country.
    Example: "+1 204-253-9411 ext. 123"

  - `address.email` (string,null)
    Email for the address owner.
    Example: "example@example.com"

  - `address.company_name` (string,null)
    If this is a business address, then the company name should be specified here.
    Example: "The Home Depot"

  - `address.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.
    Example: "1999 Bishop Grandin Blvd."

  - `address.address_line2` (string,null)
    The second line of the street address.  For some addresses, this line may not be needed.
    Example: "Unit 408"

  - `address.address_line3` (string,null)
    The third line of the street address.  For some addresses, this line may not be needed.
    Example: "Building #7"

  - `address.city_locality` (string)
    The name of the city or locality
    Example: "Winnipeg"

  - `address.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.
    Example: "Manitoba"

  - `address.postal_code` (string)
    postal code
    Example: "78756-3717"

  - `address.country_code` (string)
    The two-letter [ISO 3166-1 country code](https://en.wikipedia.org/wiki/ISO_3166-1)
    Example: "CA"

  - `address.address_residential_indicator` (string)
    Indicates whether this is a residential address.
    Enum: "unknown", "yes", "no"

## Response 200 fields (application/json):

  - `score` (number, required)
    A confidence score between zero and one that indicates how certain the API is that it understood the text.

  - `address` (object, required)
    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.

  - `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.
    Example: "John Doe"

  - `address.phone` (string)
    The phone number of a contact person at this address.  The format of this phone number varies depending on the country.
    Example: "+1 204-253-9411 ext. 123"

  - `address.email` (string,null)
    Email for the address owner.
    Example: "example@example.com"

  - `address.company_name` (string,null)
    If this is a business address, then the company name should be specified here.
    Example: "The Home Depot"

  - `address.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.
    Example: "1999 Bishop Grandin Blvd."

  - `address.address_line2` (string,null)
    The second line of the street address.  For some addresses, this line may not be needed.
    Example: "Unit 408"

  - `address.address_line3` (string,null)
    The third line of the street address.  For some addresses, this line may not be needed.
    Example: "Building #7"

  - `address.city_locality` (string)
    The name of the city or locality
    Example: "Winnipeg"

  - `address.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.
    Example: "Manitoba"

  - `address.postal_code` (string)
    postal code
    Example: "78756-3717"

  - `address.country_code` (string)
    The two-letter [ISO 3166-1 country code](https://en.wikipedia.org/wiki/ISO_3166-1)
    Example: "CA"

  - `address.address_residential_indicator` (string)
    Indicates whether this is a residential address.
    Enum: "unknown", "yes", "no"

  - `entities` (array, 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.

  - `entities.type` (string, required)
    The Entity type (e.g. "weight", "person", "address_line1", etc.)

  - `entities.score` (number, required)
    A confidence score between zero and one that indicates how certain the API is that it correctly recognized this entity

  - `entities.text` (string, required)
    The substring from the original text that was recognized as this entity

  - `entities.start_index` (integer, required)
    The index of the first character of this entity within the original text

  - `entities.end_index` (integer, required)
    The index of the last character of this entity within the original text

  - `entities.result` (object)
    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.

## Response 400 fields (application/json):

  - `request_id` (string, required)
    A UUID that uniquely identifies the request id.
This can be given to the support team to help debug non-trivial issues that may occur
    Example: "aa3d8e8e-462b-4476-9618-72db7f7b7009"

  - `errors` (array, required)
    The errors associated with the failed API call

  - `errors.error_source` (string, required)
    The source of the error, as indicated by the name this informs us if the API call failed because of the
carrier, the order source, or the ShipEngine API itself.
    Enum: "carrier", "order_source", "shipengine"

  - `errors.error_type` (string, required)
    The type of error
    Enum: "account_status", "business_rules", "validation", "security", "system", "integrations"

  - `errors.error_code` (string, required)
    The error code specified for the failed API Call
    Enum: "auto_fund_not_supported", "batch_cannot_be_modified", "carrier_conflict", "carrier_disconnected", "carrier_not_connected", "carrier_not_supported", "confirmation_not_supported", "default_warehouse_cannot_be_deleted", "field_conflict", "field_value_required", "forbidden", "identifier_conflict", "identifiers_must_match", "insufficient_funds", "invalid_address", "invalid_billing_plan", "invalid_field_value", "invalid_identifier", "invalid_status", "invalid_string_length", "label_images_not_supported", "meter_failure", "order_source_not_active", "rate_limit_exceeded", "refresh_not_supported", "request_body_required", "return_label_not_supported", "settings_not_supported", "subscription_inactive", "terms_not_accepted", "tracking_not_supported", "trial_expired", "unauthorized", "unknown", "unspecified", "verification_failure", "warehouse_conflict", "webhook_event_type_conflict", "customs_items_required", "incompatible_paired_labels", "invalid_charge_event", "invalid_object", "no_rates_returned", "file_not_found", "shipping_rule_not_found", "service_not_determined", "no_rates_returned", "funding_source_registration_in_progress", "insurance_failure", "funding_source_missing_configuration", "funding_source_error"

  - `errors.message` (string, required)
    An error message associated with the failed API call
    Example: "Body of request cannot be null."

  - `errors.carrier_id` (string)
    A string that uniquely identifies the carrier that generated the error.
    Example: "se-28529731"

  - `errors.carrier_code` (string)
    The name of the shipping carrier that generated the error, such as fedex, dhl_express, stamps_com, etc.
    Example: "dhl_express"

  - `errors.field_name` (string)
    The name of the field that caused the error
    Example: "shipment.ship_to.phone_number"

## Response 500 fields (application/json):

  - `request_id` (string, required)
    A UUID that uniquely identifies the request id.
This can be given to the support team to help debug non-trivial issues that may occur
    Example: "aa3d8e8e-462b-4476-9618-72db7f7b7009"

  - `errors` (array, required)
    The errors associated with the failed API call

  - `errors.error_source` (string, required)
    The source of the error, as indicated by the name this informs us if the API call failed because of the
carrier, the order source, or the ShipEngine API itself.
    Enum: "carrier", "order_source", "shipengine"

  - `errors.error_type` (string, required)
    The type of error
    Enum: "account_status", "business_rules", "validation", "security", "system", "integrations"

  - `errors.error_code` (string, required)
    The error code specified for the failed API Call
    Enum: "auto_fund_not_supported", "batch_cannot_be_modified", "carrier_conflict", "carrier_disconnected", "carrier_not_connected", "carrier_not_supported", "confirmation_not_supported", "default_warehouse_cannot_be_deleted", "field_conflict", "field_value_required", "forbidden", "identifier_conflict", "identifiers_must_match", "insufficient_funds", "invalid_address", "invalid_billing_plan", "invalid_field_value", "invalid_identifier", "invalid_status", "invalid_string_length", "label_images_not_supported", "meter_failure", "order_source_not_active", "rate_limit_exceeded", "refresh_not_supported", "request_body_required", "return_label_not_supported", "settings_not_supported", "subscription_inactive", "terms_not_accepted", "tracking_not_supported", "trial_expired", "unauthorized", "unknown", "unspecified", "verification_failure", "warehouse_conflict", "webhook_event_type_conflict", "customs_items_required", "incompatible_paired_labels", "invalid_charge_event", "invalid_object", "no_rates_returned", "file_not_found", "shipping_rule_not_found", "service_not_determined", "no_rates_returned", "funding_source_registration_in_progress", "insurance_failure", "funding_source_missing_configuration", "funding_source_error"

  - `errors.message` (string, required)
    An error message associated with the failed API call
    Example: "Body of request cannot be null."

  - `errors.carrier_id` (string)
    A string that uniquely identifies the carrier that generated the error.
    Example: "se-28529731"

  - `errors.carrier_code` (string)
    The name of the shipping carrier that generated the error, such as fedex, dhl_express, stamps_com, etc.
    Example: "dhl_express"

  - `errors.field_name` (string)
    The name of the field that caused the error
    Example: "shipment.ship_to.phone_number"