Skip to main content
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.
  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. step 1 icon 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
step 2 icon The path must be prefixed with /v2.
Address V2
https://api.goshippo.com/v2/addresses/
legacy Address
https://api.goshippo.com/addresses/
step 3 icon 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
}
step 4 icon The returned address is not stored. step 5 icon 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