---
title: "Validate address"
method: GET
path: "/v2/addresses/validate"
tags: ["Validation"]
---

# Validate address

`GET /v2/addresses/validate`

Returns validation test results along with a recommended address. Validates both US and international addresses.

**US required combinations**

- state_province + city_locality + address_line_1
- or address_line_1 + postal_code

**International required combinations**

- city_locality + address_line_1

## Query parameters

- `name` string — The name of the addressee
- `organization` string — The organization of the addressee
- `address_line_1` string, required — The first line of the address
- `address_line_2` string — The second line of the address. Must be percent encoded when passed as a query parameter (e.g. `#200` → `%23200`).
- `city_locality` string — The city or locality of the address
- `state_province` string — The state, province, county, or municipal division
- `postal_code` string — The postal code or zip code
- `country_code` 'AE' | 'AR' | 'AT' | 'AU' | 'AX' | 'AZ' | 'BA' | 'BD' | 'BE' | 'BG' | 'BH' | 'BM' | 'BN' | 'BR' | 'BS' | 'BW' | 'BY' | 'CA' | 'CH' | 'CL' | 'CO' | 'CN' | 'CY' | 'CZ' | 'DE' | 'DK' | 'EC' | 'EE' | 'EG' | 'ES' | 'FI' | 'FO' | 'FR' | 'GB' | 'GE' | 'GF' | 'GG' | 'GI' | 'GP' | 'GR' | 'GU' | 'HK' | 'HR' | 'HU' | 'ID' | 'IE' | 'IL' | 'IM' | 'IN' | 'IS' | 'IT' | 'JE' | 'JO' | 'JP' | 'KR' | 'KY' | 'KW' | 'KZ' | 'LB' | 'LI' | 'LT' | 'LU' | 'LV' | 'MA' | 'MC' | 'MD' | 'ME' | 'MK' | 'MO' | 'MP' | 'MQ' | 'MT' | 'MX' | 'MY' | 'NA' | 'NL' | 'NO' | 'NZ' | 'OM' | 'PE' | 'PH' | 'PL' | 'PM' | 'PR' | 'PT' | 'PY' | 'QA' | 'RE' | 'RO' | 'RU' | 'SA' | 'SC' | 'SE' | 'SG' | 'SI' | 'SK' | 'SM' | 'SR' | 'TH' | 'TN' | 'TR' | 'TW' | 'UA' | 'US' | 'UY' | 'VN' | 'WE' | 'YT' | 'ZA', required — ISO2 country codes

## Response `200`

Successful Response

- ValidationResponse
  - `original_address` OriginalAddress, required
    - `address_line_1` string, nullable
    - `address_line_2` string, nullable
    - `city_locality` string, nullable
    - `state_province` string, nullable
    - `postal_code` string, nullable
    - `country_code` string, nullable
    - `name` string, nullable
    - `organization` string, nullable
    - `phone` string, nullable
    - `email` string, email, nullable
  - `recommended_address` RecommendedAddress — The recommended address is an address we recommend the consumer to use. The attributes have less constraints all values may be NoneType
    - `address_line_1` string, nullable
    - `address_line_2` string, nullable
    - `city_locality` string, nullable
    - `state_province` string, nullable
    - `postal_code` string, nullable
    - `country_code` string, nullable
    - `name` string, nullable
    - `organization` string, nullable
    - `phone` string, nullable
    - `email` string, email, nullable
    - `complete_address` string, nullable
    - `confidence_result` union, required
      - ConfidenceHigh
        - `score` 'high'
        - `code` string, required
        - `description` string, nullable
      - ConfidenceMedium
        - `score` 'medium'
        - `code` string, required
        - `description` string, nullable
      - ConfidenceLow
        - `score` 'low'
        - `code` string, required
        - `description` string, nullable
  - `analysis` Analysis, required
    - `validation_result` union, required
      - ResultValid
        - `value` 'valid'
        - `reasons` ValidReason[]
          - `code` 'address_vacant' | 'address_found' | 'address_found_non_postal_match' | 'alternate_address_found' | 'unique_zip_post_code_found' | 'military_zip_found' | 'address_lacslink_true', required — Value descriptions: `address_vacant`: Address has been marked as vacant by the postal authority after 90 days of inactivity. `address_found`: The entire address is present in the database. `address_found_non_postal_match`: The address was confirmed using non-postal data sources. `alternate_address_found`: An alternate/better address has been found in the database. `unique_zip_post_code_found`: The address has a unique zip code. `military_zip_found`: The address has a military/diplomatic zip code. `address_lacslink_true`: The inputted address was found with the LACS Link indicator set as true.
          - `type` 'info' | 'warning' | 'correction' | 'error', required
          - `description` string, required
      - ResultPartiallyValid
        - `value` 'partially_valid'
        - `reasons` PartiallyValidReason[]
          - `code` 'address_found' | 'address_vacant' | 'address_confirmed_missing_secondary' | 'address_confirmed_invalid_secondary' | 'address_found_non_postal_match' | 'alternate_address_found' | 'military_zip_found' | 'address_lacslink_true' | 'zip_post_code_corrected' | 'city_state_corrected' | 'address_used_name_org' | 'dual_address_found' | 'address_found_direction_change' | 'address_found_suffix_modified' | 'street_name_corrected' | 'address_abbreviation_fixed' | 'city_name_corrected' | 'zip_plus_four_corrected' | 'unique_zip_post_code_found' | 'city_state_not_found' | 'multiple_address_same_zip_post_code' | 'multiple_zip_plus_four_found' | 'address_organization_corrected' | 'address_premise_info_corrected' | 'address_premise_type_corrected' | 'address_secondary_info_corrected' | 'address_secondary_type_corrected' | 'street_direction_corrected' | 'street_component_corrected' | 'city_locality_corrected' | 'state_province_corrected', required — Value descriptions: `address_found`: The entire address is present in the database. `address_vacant`: Address has been marked as vacant by the postal authority after 90 days of inactivity. `address_confirmed_missing_secondary`: The main address is present in the database, but it is missing secondary information (apartment, suite, etc.). `address_confirmed_invalid_secondary`: The main address is present in the database, but the submitted secondary information (apartment, suite, etc.) was not recognized. `address_found_non_postal_match`: The address was confirmed using non-postal data sources. `alternate_address_found`: An alternate/better address has been found in the database. `military_zip_found`: The address has a military/diplomatic zip code. `address_lacslink_true`: The inputted address was found with the LACS Link indicator set as true. `zip_post_code_corrected`: The zip code has been corrected to a different ZIP Code. `city_state_corrected`: The spelling of the city name and/or state abbreviation has been corrected to the standard spelling. `address_used_name_org`: Information in the name or organization input field was determined to be part of the address. `dual_address_found`: The inputted address contained two addresses. `address_found_direction_change`: Address found by changing the cardinal direction (North, South, East, West). `address_found_suffix_modified`: An address component (i.e., directional or suffix only) was added, changed, or deleted in order to achieve a match. `street_name_corrected`: Address found by correcting the spelling of the street name. `address_abbreviation_fixed`: Address inputted was standardized for abbreviations according to postal authority rules. `city_name_corrected`: The city name in the submitted address has been corrected according to postal authority rules. `zip_plus_four_corrected`: The zip plus four in the submitted address has been moved to a new zip code. `unique_zip_post_code_found`: The address has a unique zip code. `city_state_not_found`: The city and state in the submitted address could not be verified as corresponding to the given ZIP Code. `multiple_address_same_zip_post_code`: Multiple addresses were returned, with the same ZIP code. `multiple_zip_plus_four_found`: More than one ZIP+4 Code was found to satisfy the address as submitted. `address_organization_corrected`: Address found by correcting the organization name inputted. `address_premise_info_corrected`: Address found by correcting the premise information inputted. `address_premise_type_corrected`: Address found by correcting the type of premise inputted. `address_secondary_info_corrected`: Address found by correcting the secondary information inputted. `address_secondary_type_corrected`: Address found by correcting the type of secondary information inputted (from "Apt" to "Ste"). `street_direction_corrected`: Address found by correcting the street pre/post directional (from "W" to "E"). `street_component_corrected`: Address found by correcting the street leading or trailing type (from "Rd" to "Ave"). `city_locality_corrected`: The city/locality has been corrected. `state_province_corrected`: The state/province has been corrected.
          - `type` 'info' | 'warning' | 'correction' | 'error', required
          - `description` string, required
      - ResultInvalid
        - `value` 'invalid'
        - `reasons` InvalidReason[]
          - `code` 'address_vacant' | 'address_not_found' | 'address_found_non_postal_match' | 'address_confirmed_missing_secondary' | 'address_abbreviation_fixed' | 'zip_post_code_not_found' | 'zip_post_code_corrected' | 'zip_plus_four_not_found' | 'multiple_address_same_zip_post_code' | 'incomplete_address_input' | 'multiple_zip_plus_four_found' | 'address_invalid_street_delivery' | 'address_premise_invalid' | 'address_confirmed_invalid_secondary' | 'address_suffix_direction_not_found' | 'address_street_not_found' | 'address_incomplete_for_geocode' | 'address_premise_missing' | 'geocode_not_found', required — Value descriptions: `address_vacant`: Address has been marked as vacant by the postal authority after 90 days of inactivity. `address_not_found`: Address is not present in the database `address_found_non_postal_match`: The address was confirmed using non-postal data sources. `address_confirmed_missing_secondary`: The main address is present in the database, but it is missing secondary information (apartment, suite, etc.). `address_abbreviation_fixed`: Address inputted was standardized for abbreviations according to postal authority rules. `zip_post_code_not_found`: The ZIP Code in the submitted address could not be found because neither a valid city and state, nor valid 5-digit ZIP Code was present. `zip_post_code_corrected`: The zip code has been corrected to a different ZIP Code. `zip_plus_four_not_found`: This address is not present in the database for the provided zip code. `multiple_address_same_zip_post_code`: Multiple addresses were returned, with the same ZIP code. `incomplete_address_input`: The submitted address did not contain sufficiently complete or correct data to determine a single ZIP+4 Code. `multiple_zip_plus_four_found`: More than one ZIP+4 Code was found to satisfy the address as submitted. `address_invalid_street_delivery`: The postal authority does not provide street delivery service for this ZIP Code. `address_premise_invalid`: The premise (house or building) number for the address is not valid. `address_confirmed_invalid_secondary`: The main address is present in the database, but the submitted secondary information (apartment, suite, etc.) was not recognized. `address_suffix_direction_not_found`: The combination of directionals (N, E, SW, etc) and the suffix (AVE, ST, BLVD) is not correct and produced multiple possible matches. `address_street_not_found`: Could not match the input street to a unique street name. `address_incomplete_for_geocode`: The input address did not provide enough valid information to append a geocode. `address_premise_missing`: The premise (house or building) number for the address is missing in the input. `geocode_not_found`: Geocode could not be appended for the input locality or postal code.
          - `type` 'info' | 'warning' | 'correction' | 'error', required
          - `description` string, required
    - `address_type` 'unknown' | 'residential' | 'commercial' | 'po_box' | 'military' — The residential/commercial type of the address from the delivery/pickup standpoint `unknown` At the moment it is not possible to establish if the address is of any known type `residential` The address is a residence `commercial` The address is associated with a business `po_box` The address is a PO Box `military` The address is a military address
    - `changed_attributes` AddressAttributes[], nullable
  - `geo` Geo
    - `latitude` number, required
    - `longitude` number, required

## Other responses

- `422` — Unprocessable Entity
- `5XX` — Server Error

---

[API](https://skmtc.net/goshippo/apis/shippo-address-api.md) · [All operations](https://skmtc.net/goshippo/apis/shippo-address-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/goshippo/shippo-address-api/revisions/26fcc6af452a/schema)