> ## Documentation Index
> Fetch the complete documentation index at: https://docs.goshippo.com/llms.txt
> Use this file to discover all available pages before exploring further.
## Submitting Feedback
If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:
POST https://docs.goshippo.com/feedback
```json
{
"path": "/api-reference/validation/validate-address",
"feedback": "Description of the issue"
}
```
Only submit feedback when you have something specific and actionable to report.
# Validate address
> 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
## OpenAPI
````yaml /api-reference/addressesapi/address_v2.yaml get /v2/addresses/validate
openapi: 3.1.0
info:
title: Shippo Address API
summary: The Shippo Address API
description: >-
Address book, Address validation, and Address parsing
[https://goshippo.com](https://goshippo.com/)
x-logo:
url: https://docs.goshippo.com/images/shippo-logo.svg
contact:
name: Shippo Support
url: https://support.goshippo.com/hc
email: support@shippo.zendesk.com
version: '0.1'
servers:
- url: https://api.goshippo.com
security: []
tags:
- name: Address Book
description: Store, retrieve, modify, and delete your address book contacts
- name: Validation
description: Check your address is valid before creating shipping labels
- name: Parser
description: Convert address strings into a correctly formatted address object
paths:
/v2/addresses/validate:
get:
tags:
- Validation
summary: Validate address
description: >-
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
operationId: validate_address_addresses_validate_get
parameters:
- name: name
in: query
required: false
schema:
type: string
maxLength: 64
title: Name
description: The name of the addressee
example: Wilson
description: The name of the addressee
- name: organization
in: query
required: false
schema:
type: string
maxLength: 100
description: The organization of the addressee
example: Shippo
title: Organization
description: The organization of the addressee
- name: address_line_1
in: query
required: true
schema:
type: string
maxLength: 100
minLength: 1
title: Address Line 1
description: The first line of the address
example: 731 Market Street
description: The first line of the address
- name: address_line_2
in: query
required: false
schema:
type: string
maxLength: 50
description: >-
The second line of the address. Must be percent encoded when
passed as a query parameter (e.g. `#200` → `%23200`).
example: '#200'
title: Address Line 2
description: >-
The second line of the address. Must be percent encoded when passed
as a query parameter (e.g. `#200` → `%23200`).
- name: city_locality
in: query
required: false
schema:
type: string
maxLength: 64
description: The city or locality of the address
example: San Francisco
title: City Locality
description: The city or locality of the address
- name: state_province
in: query
required: false
schema:
type: string
maxLength: 32
description: The state, province, county, or municipal division
example: CA
title: State Province
description: The state, province, county, or municipal division
- name: postal_code
in: query
required: false
schema:
type: string
maxLength: 16
description: The postal code or zip code
example: '94103'
title: Postal Code
description: The postal code or zip code
- name: country_code
in: query
required: true
schema:
allOf:
- $ref: '#/components/schemas/CountryCodeISO2'
description: The ISO 3166 country code
example: US
title: Country Code
description: The ISO 3166 country code
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationResponse'
'422':
content:
application/json:
example:
detail:
- type: string_too_short
loc:
- query
- address_line_1
msg: String should have at least 1 character
input: ''
ctx:
min_length: 1
url: https://errors.pydantic.dev/2.3/v/string_too_short
schema:
$ref: '#/components/schemas/UnprocessableEntityResponse'
description: Unprocessable Entity
5XX:
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorResponse'
description: Server Error
security:
- Shippo_Token: []
x-codeSamples:
- lang: cURL
label: curl
source: >-
curl -i -X GET \
'https://api.goshippo.com/v2/addresses/validate?name=Wilson&organization=Shippo&address_line_1=731%20Market%20Street&address_line_2=%23200&city_locality=San%20Francisco&state_province=CA&postal_code=94103&country_code=US'
\
-H 'Authorization: ShippoToken '
components:
schemas:
CountryCodeISO2:
type: string
enum:
- 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
title: CountryCodeISO2
description: ISO2 country codes
ValidationResponse:
properties:
original_address:
$ref: '#/components/schemas/OriginalAddress'
recommended_address:
anyOf:
- $ref: '#/components/schemas/RecommendedAddress'
- type: 'null'
analysis:
$ref: '#/components/schemas/Analysis'
geo:
anyOf:
- $ref: '#/components/schemas/Geo'
- type: 'null'
type: object
required:
- original_address
- analysis
title: ValidationResponse
UnprocessableEntityResponse:
properties:
detail:
items:
$ref: '#/components/schemas/ErrorDetail'
type: array
title: Detail
description: Details of the issue with the request.
type: object
required:
- detail
title: UnprocessableEntityResponse
description: A response for invalid requests with details of the issue.
InternalServerErrorResponse:
properties:
message:
type: string
title: Message
description: The error message for an internal server error
default: Internal Server Error
trace_id:
type: string
title: Trace Id
description: >-
The OpenTelemetry trace identifier that is unique to the request. A
valid trace identifier is a 16-byte array with at least one non-zero
byte
example: b562cab2e9200ac3e11474cc877580e1
type: object
required:
- trace_id
title: InternalServerErrorResponse
OriginalAddress:
properties:
address_line_1:
anyOf:
- type: string
- type: 'null'
title: Address Line 1
address_line_2:
anyOf:
- type: string
- type: 'null'
title: Address Line 2
city_locality:
anyOf:
- type: string
- type: 'null'
title: City Locality
state_province:
anyOf:
- type: string
- type: 'null'
title: State Province
postal_code:
anyOf:
- type: string
- type: 'null'
title: Postal Code
country_code:
anyOf:
- type: string
- type: 'null'
title: Country Code
name:
anyOf:
- type: string
- type: 'null'
title: Name
organization:
anyOf:
- type: string
- type: 'null'
title: Organization
phone:
anyOf:
- type: string
- type: 'null'
title: Phone
email:
anyOf:
- type: string
format: email
- type: 'null'
title: Email
type: object
title: OriginalAddress
RecommendedAddress:
properties:
address_line_1:
anyOf:
- type: string
- type: 'null'
title: Address Line 1
address_line_2:
anyOf:
- type: string
- type: 'null'
title: Address Line 2
city_locality:
anyOf:
- type: string
- type: 'null'
title: City Locality
state_province:
anyOf:
- type: string
- type: 'null'
title: State Province
postal_code:
anyOf:
- type: string
- type: 'null'
title: Postal Code
country_code:
anyOf:
- type: string
- type: 'null'
title: Country Code
name:
anyOf:
- type: string
- type: 'null'
title: Name
organization:
anyOf:
- type: string
- type: 'null'
title: Organization
phone:
anyOf:
- type: string
- type: 'null'
title: Phone
email:
anyOf:
- type: string
format: email
- type: 'null'
title: Email
complete_address:
anyOf:
- type: string
- type: 'null'
title: Complete Address
confidence_result:
oneOf:
- $ref: '#/components/schemas/ConfidenceHigh'
- $ref: '#/components/schemas/ConfidenceMedium'
- $ref: '#/components/schemas/ConfidenceLow'
title: Confidence Result
discriminator:
propertyName: score
mapping:
high:
$ref: '#/components/schemas/ConfidenceHigh'
low:
$ref: '#/components/schemas/ConfidenceLow'
medium:
$ref: '#/components/schemas/ConfidenceMedium'
type: object
required:
- confidence_result
title: RecommendedAddress
description: >-
The recommended address is an address we recommend the consumer to use.
The attributes have less constraints
all values may be NoneType
Analysis:
properties:
validation_result:
oneOf:
- $ref: '#/components/schemas/ResultValid'
- $ref: '#/components/schemas/ResultPartiallyValid'
- $ref: '#/components/schemas/ResultInvalid'
title: Validation Result
discriminator:
propertyName: value
mapping:
invalid:
$ref: '#/components/schemas/ResultInvalid'
partially_valid:
$ref: '#/components/schemas/ResultPartiallyValid'
valid:
$ref: '#/components/schemas/ResultValid'
address_type:
allOf:
- $ref: '#/components/schemas/AddressType'
default: unknown
changed_attributes:
anyOf:
- items:
$ref: '#/components/schemas/AddressAttributes'
type: array
uniqueItems: true
- type: 'null'
title: Changed Attributes
type: object
required:
- validation_result
title: Analysis
Geo:
properties:
latitude:
type: number
title: Latitude
longitude:
type: number
title: Longitude
type: object
required:
- latitude
- longitude
title: Geo
ErrorDetail:
properties:
type:
type: string
title: Type
description: The type of error
examples:
- missing
loc:
items:
type: string
type: array
title: Loc
description: The location of the error
examples:
- - query
- country_code
msg:
type: string
title: Msg
description: The error message
examples:
- Field required
input:
anyOf:
- {}
- type: 'null'
title: Input
description: The input values for this field
examples:
- 'null'
type: object
required:
- type
- loc
- msg
title: ErrorDetail
ConfidenceHigh:
properties:
score:
type: string
enum:
- high
const: high
title: Score
default: high
code:
type: string
title: Code
description:
anyOf:
- type: string
- type: 'null'
title: Description
type: object
required:
- code
title: ConfidenceHigh
ConfidenceMedium:
properties:
score:
type: string
enum:
- medium
const: medium
title: Score
default: medium
code:
type: string
title: Code
description:
anyOf:
- type: string
- type: 'null'
title: Description
type: object
required:
- code
title: ConfidenceMedium
ConfidenceLow:
properties:
score:
type: string
enum:
- low
const: low
title: Score
default: low
code:
type: string
title: Code
description:
anyOf:
- type: string
- type: 'null'
title: Description
type: object
required:
- code
title: ConfidenceLow
ResultValid:
properties:
value:
const: valid
title: Value
default: valid
reasons:
items:
$ref: '#/components/schemas/ValidReason'
type: array
uniqueItems: true
title: Reasons
default: []
type: object
title: ResultValid
ResultPartiallyValid:
properties:
value:
const: partially_valid
title: Value
default: partially_valid
reasons:
items:
$ref: '#/components/schemas/PartiallyValidReason'
type: array
uniqueItems: true
title: Reasons
default: []
type: object
title: ResultPartiallyValid
ResultInvalid:
properties:
value:
const: invalid
title: Value
default: invalid
reasons:
items:
$ref: '#/components/schemas/InvalidReason'
type: array
uniqueItems: true
title: Reasons
default: []
type: object
title: ResultInvalid
AddressType:
type: string
enum:
- unknown
- residential
- commercial
- po_box
- military
title: AddressType
description: >-
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
AddressAttributes:
type: string
enum:
- address_line_1
- address_line_2
- city_locality
- state_province
- postal_code
- country_code
title: AddressAttributes
ValidReason:
properties:
code:
$ref: '#/components/schemas/ValidReasonCode'
type:
$ref: '#/components/schemas/ReasonType'
description:
type: string
title: Description
type: object
required:
- code
- type
- description
title: ValidReason
PartiallyValidReason:
properties:
code:
$ref: '#/components/schemas/PartiallyValidReasonCode'
type:
$ref: '#/components/schemas/ReasonType'
description:
type: string
title: Description
type: object
required:
- code
- type
- description
title: PartiallyValidReason
InvalidReason:
properties:
code:
$ref: '#/components/schemas/InvalidReasonCode'
type:
$ref: '#/components/schemas/ReasonType'
description:
type: string
title: Description
type: object
required:
- code
- type
- description
title: InvalidReason
ValidReasonCode:
type: string
enum:
- address_vacant
- address_found
- address_found_non_postal_match
- alternate_address_found
- unique_zip_post_code_found
- military_zip_found
- address_lacslink_true
title: ValidReasonCode
description: >-
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.
ReasonType:
type: string
enum:
- info
- warning
- correction
- error
title: ReasonType
PartiallyValidReasonCode:
type: string
enum:
- 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
title: PartiallyValidReasonCode
description: >-
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.
InvalidReasonCode:
type: string
enum:
- 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
title: InvalidReasonCode
description: >-
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.
securitySchemes:
Shippo_Token:
type: apiKey
description: |
Enter your shippo token with the ShippoToken prefix.
Example: `ShippoToken shippo_live_xxxx`
in: header
name: Authorization
x-default: 'ShippoToken '
````