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.

cURLValidate address response
Copy
Copied
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>'
Copy
Copied
{
    "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.


Please select an address and click Validate to get started.


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.

  1. When creating a new address object using the validate option.
  2. 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 validationlegacy Address validation
Copy
Copied
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>'
Copy
Copied
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 V2legacy Address
Copy
Copied
https://api.goshippo.com/v2/addresses/
Copy
Copied
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 responselegacy Address response
Copy
Copied
{
  "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
  }
}
Copy
Copied
{
    "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 FieldV2 Address FieldNotes
Deprecated Fields
is_complete
object_created
object_updated
object_id
object_owner
street_no
street3
phone
email
test
validation_resultsMoved to analysis but modified
metadata
V1 Address FieldV2 Address FieldNotes
original_address , recommended_address
namename
companyorganization
street1address_line_1
street2address_line_2
citycity_locality
statestate_province
zippostal_code
countrycountry_code
V1 Address FieldV2 Address FieldNotes
recommended_address (exclusive fields)
recommended_address is present if we believe there is a more accurate version of the address
complete_addressThe full address in one string whenever available
confidence_resultContains 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 FieldV2 Address FieldNotes
analysis
is_residentialaddress_typechanged from boolean to an enum. residential, commercial, unknown, po_box, military
validation_resultsvalidation_resultschanged from boolean to an object.
validation_results.is_validvalidation_results.valueChanged from Bool to enum. valid, partially_valid, invalid
validation_results.messagesvalidation_results.reasonsEach 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_attributeslist of fields changed in the recommended address from the original address.
V1 Address FieldV2 Address FieldNotes
geo
latitude
longitude