Address validation

Address validation is a service that tests your address to check if it is valid. By checking for invalid addresses and instantly correcting them to ensure accurate addresses, this helps prevent failed deliveries and address correction surcharges and allows you to protect your bottom line. You can have customers validate addresses through the Addresses API during checkout or you can validate addresses while you are creating labels. The returned results include a validation_result that indicates if the address is valid. If the validation identifies changes needed in order to make your address valid, the API response recommends a new address in recommended_address.

Using address validation

If you are interested in using Shippo’s Address Validation API or have any questions about pricing, please contact our sales team.

Validate an address

To validate an address, follow this example.

cURL

curl -i -X GET \
  'https://api.goshippo.com/v2/addresses/validate?address_line_1=320J Outerbelt Street&city_locality=Columbus&state_province=OH&postal_code=43213&country_code=US&organization=Shippo' \
  -H 'Authorization: ShippoToken <API_TOKEN>'

Validate address response

{
    "original_address": {
        "address_line_1": "320J Outerbelt Street",
        "city_locality": "Columbus",
        "state_province": "OH",
        "postal_code": "43213",
        "country_code": "US",
        "organization": "Shippo"
    },
    "recommended_address": {
        "address_line_1": "320 Outerbelt St",
        "address_line_2": "Ste J",
        "city_locality": "Columbus",
        "state_province": "OH",
        "postal_code": "43213",
        "country_code": "US",
        "organization": "Shippo",
        "complete_address": "Shippo; 320 Outerbelt St Ste J; Columbus OH 43213-1537; US",
        "confidence_result": {
            "score": "high",
            "code": "postal_data_match",
            "description": "The address has been completely verified to the most granular level possible."
        }
    },
    "analysis": {
        "validation_result": {
            "value": "partially_valid",
            "reasons": [
                {
                    "code": "address_abbreviation_fixed",
                    "description": "Address inputted was standardized for abbreviations according to postal authority rules."
                }
            ]
        },
        "address_type": "commercial",
        "changed_attributes": [
            "address_line_2",
            "address_line_1"
        ]
    },
    "geo": {
        "latitude": 39.98725,
        "longitude": -82.83042
    }
}

Try address validation

Try our Address Validation API using any example address from the dropdown below. You can find the breakdown of the address validation result, and the raw API response as a JSON object.

Migrate address validation

If you use the legacy Shippo validation, you may choose to update your integration to use the latest Addresses API. Use this guide to understand what has changed and what you need to do to use the latest version. The legacy address validation supported two methods for address validation.

When creating a new address object using the validate option.
Validating existing Address objects.

The latest Address API validation does not support validating addresses using the object ID of an address. The changes are as follows.

Address fields are passed as query parameters instead of fields in the body of the request.

Address V2 validation

curl -i -X GET \
  'https://api.goshippo.com/v2/addresses/validate?address_line_1=215 Clayton St&city_locality=San Francisco&state_province=CA&postal_code=94117&country_code=US&organization=Shippo' \
  -H 'Authorization: ShippoToken <API_TOKEN>'

legacy Address validation

curl -i https://api.goshippo.com/addresses/\
    -H "Authorization: ShippoToken <API_TOKEN>"\
    -d company="Shippo"\
    -d street1="215 Clayton St."\
    -d city="San Francisco"\
    -d state="CA"\
    -d zip=94117\
    -d country="US"\
    -d validate=true

The path must be prefixed with /v2.

Address V2

https://api.goshippo.com/v2/addresses/

legacy Address

https://api.goshippo.com/addresses/

The returned response includes a richer details about the validated address including the following.

A recommended_address.
A confidence_result with a score and description describing the quality of the recommended address.
analysis that includes details about the validation.
changed_attributes that lists which values changed between the original_address and the recommended_address.

Address V2 response

{
  "original_address": {
    "address_line_1": "965 Mission St # 572",
    "address_line_2": "#200",
    "city_locality": "San Francisco",
    "state_province": "CA",
    "postal_code": "94103-2921",
    "country_code": "US",
    "name": "Mr. Hippo"
  },
  "analysis": {
    "validation_result": {
      "value": "valid",
      "reasons": [
        {
          "code": "address_found",
          "description": "The entire address is present in the database."
        }
      ]
    },
    "address_type": "commercial"
  },
  "geo": {
    "latitude": 37.78152,
    "longitude": -122.40786
  }
}

legacy Address response

{
    "object_created": "2024-02-15T16:04:06.649Z",
    "object_updated": "2024-02-15T16:04:06.674Z",
    "object_id": "3af6fd3321c3468caeb5cf6d5545de36",
    "is_complete": true,
    "validation_results": {
        "is_valid": true,
        "messages": [
            {
                "source": "Shippo Address Validator",
                "code": "Default Match",
                "type": "address_warning",
                "text": "More information, such as an apartment or suite number, may give a more specific address."
            }
        ]
    },
    "object_owner": "adrian.collins@goshippo.com",
    "name": "Mr Hippo",
    "company": "",
    "street_no": "",
    "street1": "965 Mission St # 572",
    "street2": "",
    "street3": "",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94103-2921",
    "country": "US",
    "longitude": -122.40786,
    "latitude": 37.78152,
    "phone": "4151234567",
    "email": "mrhippo@goshippo.com",
    "is_residential": false,
    "metadata": "",
    "test": true
}

The returned address is not stored.

The following fields have changed.

V1 Address Field	V2 Address Field	Notes
Deprecated Fields
is_complete
object_created
object_updated
object_id
object_owner
street_no
street3
phone
email
test
validation_results		Moved to analysis but modified
metadata

V1 Address Field	V2 Address Field	Notes
original_address , recommended_address
name	name
company	organization
street1	address_line_1
street2	address_line_2
city	city_locality
state	state_province
zip	postal_code
country	country_code

V1 Address Field	V2 Address Field	Notes
recommended_address (exclusive fields)
recommended_address is present if we believe there is a more accurate version of the address
	complete_address	The full address in one string whenever available
	confidence_result	Contains the score field which takes values of high, medium, low; contains the code field which is the machine readable explanation to the score; and the description field which is the human friendly explanation to the score.

V1 Address Field	V2 Address Field	Notes
analysis
is_residential	address_type	changed from boolean to an enum. `residential`, `commercial`, `unknown`, `po_box`, `military`
validation_results	validation_results	changed from boolean to an object.
validation_results.is_valid	validation_results.value	Changed from Bool to enum. `valid`, `partially_valid`, `invalid`
validation_results.messages	validation_results.reasons	Each reason is an object containing the code and the description. The code is the machine readable explanation to why the address is valid, partially valid, or invalid. And the description is the human friendly value for the same.
	changed_attributes	list of fields changed in the recommended address from the original address.

V1 Address Field	V2 Address Field	Notes
geo
	latitude
	longitude

Overview

Get started

AI & agents

Guides

Concepts

Using address validation

Validate an address

Try address validation

Migrate address validation

​Using address validation

​Validate an address

​Try address validation

​Migrate address validation

Using address validation

Validate an address

Try address validation

Migrate address validation