openapi: 3.0.1
info:
title: International Address Autocomplete Lookup API
version: '0.9'
description: "This API returns suggestions that are fully verified global addresses.\nUses fuzzy logic during searching to:\nAllow for missing directionals and street suffixes.\nAllow substitution of street suffixes and unit designators. E.g., ST is accepted for AVE; APT is accepted for UNIT, etc.\nAllow full or partial spelling of street suffixes and unit designators. E.g., ST can be spelled as STR or STREET and still match.\nFilters and preferences allow for multiple cities in a single country.\nNote: Effective with the adoption of the V2 version of International Address Autocomplete, lookup usage will be based on the final selection of an address rather than per keystroke.\n\nBy default, the character set returned will be the native set for that country. If any latin characters are provided in the input (excluding numerics), the latin set will be returned. Character sets include:\nCyrillic\nGreek\nHebrew\nKanji (Japanese)\nSimplified Chinese\nArabic\nThai\nHangul (Korean)\n\nSupports the following 242 countries: \nAfghanistan\tAFG\nAlbania\tALB\nAlgeria\tDZA\nAndorra\tAND\nAngola\tAGO\nAnguilla\tAIA\nAntarctica\tATA\nAntigua and Barbuda\tATG\nArgentina\tARG\nArmenia\tARM\nAruba\tABW\nAustralia\tAUS\nAustria\tAUT\nAzerbaijan\tAZE\nBahamas\tBHS\nBahrain\tBHR\nBangladesh\tBGD\nBarbados\tBRB\nBelarus\tBLR\nBelgium\tBEL\nBelize\tBLZ\nBenin\tBEN\nBermuda\tBMU\nBhutan\tBTN\nBolivia\tBOL\nBonaire, Sint Eustatius and Saba\tBES\nBosnia and Herzegovina\tBIH\nBotswana\tBWA\nBouvet Island\tBVT\nBrazil\tBRA\nBritish Indian Ocean Territory\tIOT\nBrunei Darussalam\tBRN\nBulgaria\tBGR\nBurkina Faso\tBFA\nBurundi\tBDI\nCambodia\tKHM\nCameroon\tCMR\nCanada\tCAN\nCabo Verde\tCPV\nCayman Islands\tCYM\nCentral African Republic\tCAF\nChad\tTCD\nChile\tCHL\nChina\tCHN\nChristmas Island\tCXR\nCocos (Keeling) Islands\tCCK\nColombia\tCOL\nComoros\tCOM\nCongo\tCOG\nDemocratic Republic of the Congo\tCOD\nCook Islands\tCOK\nCosta Rica\tCRI\nCroatia\tHRV\nCuba\tCUB\nCuraçao\tCUW\nCyprus\tCYP\nCzechia\tCZE\nIvory Coast\tCIV\nDenmark\tDNK\nDjibouti\tDJI\nDominica\tDMA\nDominican Republic\tDOM\nEcuador\tECU\nEgypt\tEGY\nEl Salvador\tSLV\nEquatorial Guinea\tGNQ\nEritrea\tERI\nEstonia\tEST\nEswatini\tSWZ\nEthiopia\tETH\nFalkland Islands\tFLK\nFaroe Islands\tFRO\nFiji\tFJI\nFinland\tFIN\nFrance\tFRA\nFrench Guiana\tGUF\nFrench Polynesia\tPYF\nFrench Southern Territories\tATF\nGabon\tGAB\nGambia\tGMB\nGeorgia\tGEO\nGermany\tDEU\nGhana\tGHA\nGibraltar\tGIB\nGreece\tGRC\nGreenland\tGRL\nGrenada\tGRD\nGuadeloupe\tGLP\nGuatemala\tGTM\nGuernsey\tGGY\nGuinea\tGIN\nGuinea-Bissau\tGNB\nGuyana\tGUY\nHaiti\tHTI\nHeard Island and McDonald Islands\tHMD\nHoly See\tVAT\nHonduras\tHND\nHong Kong\tHKG\nHungary\tHUN\nIceland\tISL\nIndia\tIND\nIndonesia\tIDN\nIslamic Republic of Iran\tIRN\nIraq\tIRQ\nIreland\tIRL\nIsle of Man\tIMN\nIsrael\tISR\nItaly\tITA\nJamaica\tJAM\nJapan\tJPN\nJersey\tJEY\nJordan\tJOR\nKazakhstan\tKAZ\nKenya\tKEN\nKiribati\tKIR\nDemocratic People's Republic of Korea (North Korea)\tPRK\nRepublic of Korea\tKOR\nKosovo\tXKX\nKuwait\tKWT\nKyrgyzstan\tKGZ\nLao People's Democratic Republic\tLAO\nLatvia\tLVA\nLebanon\tLBN\nLesotho\tLSO\nLiberia\tLBR\nLibya\tLBY\nLiechtenstein\tLIE\nLithuania\tLTU\nLuxembourg\tLUX\nMacao\tMAC\nRepublic of North Macedonia\tMKD\nMadagascar\tMDG\nMalawi\tMWI\nMalaysia\tMYS\nMaldives\tMDV\nMali\tMLI\nMalta\tMLT\nMartinique\tMTQ\nMauritania\tMRT\nMauritius\tMUS\nMayotte\tMYT\nMexico\tMEX\nFederated States of Micronesia\tFSM\nRepublic of Moldova\tMDA\nMonaco\tMCO\nMongolia\tMNG\nMontenegro\tMNE\nMontserrat\tMSR\nMorocco\tMAR\nMozambique\tMOZ\nMyanmar\tMMR\nNamibia\tNAM\nNauru\tNRU\nNepal\tNPL\nNetherlands\tNLD\nNew Caledonia\tNCL\nNew Zealand\tNZL\nNicaragua\tNIC\nNiger\tNER\nNigeria\tNGA\nNiue\tNIU\nNorfolk Island\tNFK\nNorway\tNOR\nOman\tOMN\nPakistan\tPAK\nPalau\tPLW\nState of Palestine\tPSE\nPanama\tPAN\nPapua New Guinea\tPNG\nParaguay\tPRY\nPeru\tPER\nPhilippines\tPHL\nPitcairn\tPCN\nPoland\tPOL\nPortugal\tPRT\nQatar\tQAT\nSouth Sudan\tSSD\nRomania\tROU\nRussian Federation\tRUS\nRwanda\tRWA\nRéunion\tREU\nSaint Barthélemy\tBLM\nSaint Helena, Ascension and Tristan da Cunha\tSHN\nSaint Kitts and Nevis\tKNA\nSaint Lucia\tLCA\nSaint Martin\tMAF\nSaint Pierre and Miquelon\tSPM\nSaint Vincent and the Grenadines\tVCT\nSamoa\tWSM\nSan Marino\tSMR\nSao Tome and Principe\tSTP\nSaudi Arabia\tSAU\nSenegal\tSEN\nSerbia\tSRB\nSeychelles\tSYC\nSierra Leone\tSLE\nSingapore\tSGP\nSint Maarten (Dutch)\tSXM\nSlovakia\tSVK\nSlovenia\tSVN\nSolomon Islands\tSLB\nSomalia\tSOM\nSouth Africa\tZAF\nSouth Georgia and the South Sandwich Islands\tSGS\nSpain\tESP\nSri Lanka\tLKA\nSudan\tSDN\nSuriname\tSUR\nSvalbard and Jan Mayen Islands\tSJM\nSweden\tSWE\nSwitzerland\tCHE\nSyrian Arab Republic\tSYR\nTaiwan\tTWN\nTajikistan\tTJK\nUnited Republic of Tanzania\tTZA\nThailand\tTHA\nTimor-Leste\tTLS\nTogo\tTGO\nTokelau\tTKL\nTonga\tTON\nTrinidad and Tobago\tTTO\nTunisia\tTUN\nTürkiye (Turkey)\tTUR\nTurkmenistan\tTKM\nTurks and Caicos Islands\tTCA\nTuvalu\tTUV\nUganda\tUGA\nUkraine\tUKR\nUnited Arab Emirates\tARE\nUnited Kingdom\tGBR\nUruguay\tURY\nUzbekistan\tUZB\nVanuatu\tVUT\nBolivarian Republic of Venezuela\tVEN\nViet Nam\tVNM\nBritish Virgin Islands\tVGB\nWallis and Futuna\tWLF\nWestern Sahara\tESH\nYemen\tYEM\nZambia\tZMB\nZimbabwe\tZWE\nÅland Islands\tALA\n"
termsOfService: https://smartystreets.com/legal/terms-of-service
license:
url: https://www.smarty.com/legal/terms-of-service
name: Smarty License
contact:
name: Smarty Support
email: support@smartystreets.com
servers:
- url: https://international-autocomplete.api.smarty.com
tags:
- name: Lookup
paths:
/v2/lookup:
get:
summary: Get Autocomplete Suggestions
tags:
- Lookup
security:
- auth-id: []
auth-token: []
- embedded-key: []
responses:
'200':
$ref: '#/components/responses/200'
'400':
description: 'Bad Request (Malformed Payload): The request was malformed in some way and could not be parsed.'
'401':
description: 'Unauthorized: The embedded key was provided incorrectly or did not match any existing, active embedded keys. Or the host in the referer header did not match a host assigned to your embedded key.'
'402':
description: 'Payment Required: There is no active subscription for the account associated with the credentials submitted with the request.'
'422':
description: 'Unprocessable Entity (Unsuitable parameters): Returns errors describing what needs to be corrected.'
'429':
description: 'Too Many Requests: When using public embedded key authentication, we restrict the number of requests coming from a given source over too short of a time. You can avoid this error by adding your IP address as an authorized host for the embedded key in question.'
operationId: get-lookup
parameters:
- $ref: '#/components/parameters/Host'
- $ref: '#/components/parameters/Referer'
- $ref: '#/components/parameters/country'
- $ref: '#/components/parameters/search'
- $ref: '#/components/parameters/max_results'
- $ref: '#/components/parameters/max_group_results'
- $ref: '#/components/parameters/geolocation'
- $ref: '#/components/parameters/include_only_locality'
- $ref: '#/components/parameters/include_only_postal_code'
/v2/lookup/{addressId}:
get:
summary: Get Autocomplete Suggestions
tags:
- Lookup
security:
- auth-id: []
auth-token: []
- embedded-key: []
responses:
'200':
$ref: '#/components/responses/detailed_200'
'400':
description: 'Bad Request (Malformed Payload): The request was malformed in some way and could not be parsed.'
'401':
description: 'Unauthorized: The embedded key was provided incorrectly or did not match any existing, active embedded keys. Or the host in the referer header did not match a host assigned to your embedded key.'
'402':
description: 'Payment Required: There is no active subscription for the account associated with the credentials submitted with the request.'
'422':
description: 'Unprocessable Entity (Unsuitable parameters): Returns errors describing what needs to be corrected.'
'429':
description: 'Too Many Requests: When using public embedded key authentication, we restrict the number of requests coming from a given source over too short of a time. You can avoid this error by adding your IP address as an authorized host for the embedded key in question.'
operationId: get-lookup-id
parameters:
- $ref: '#/components/parameters/Host'
- $ref: '#/components/parameters/Referer'
- $ref: '#/components/parameters/country'
- $ref: '#/components/parameters/address_id'
- $ref: '#/components/parameters/max_results'
- $ref: '#/components/parameters/max_group_results'
- $ref: '#/components/parameters/geolocation'
- $ref: '#/components/parameters/include_only_locality'
- $ref: '#/components/parameters/include_only_postal_code'
/lookup:
get:
tags:
- Lookup
summary: Search country and locality/administrative area/postal code
operationId: lookup-get
description: "To send one (and only one) input to the API, simply encode the field names from the table below along with their corresponding values as query string parameters in the URL of your request. Here's an example that uses locality, administrative_area, postal_code, and country fields:\n```bash\n curl -v 'https://international-postal-code.api.smarty.com/lookup?\n \tauth-id=YOUR+AUTH-ID+HERE&\n \tauth-token=YOUR+AUTH-TOKEN+HERE&\n\n \tlocality=Sao+Paulo&\n \tadministrative_area=SP&\n \tpostal_code=02516-040&\n \tcountry=Brazil'\n```\nPlease note that all query string parameter values must be url-encoded (spaces become + or %20, for example) to ensure that the data is transferred correctly. A common mistake we see is a non-encoded pound sign (#) like in an apartment number (# 409). This character, when properly encoded in a URL, becomes %23. When not encoded this character functions as the fragment identifier, which is ignored by our API servers.\n"
parameters:
- $ref: '#/components/parameters/Host_2'
- $ref: '#/components/parameters/input_id'
- $ref: '#/components/parameters/country_2'
- $ref: '#/components/parameters/locality'
- $ref: '#/components/parameters/administrative_area'
- $ref: '#/components/parameters/postal_code'
- $ref: '#/components/parameters/license'
responses:
'200':
description: OK(success!), The response body will be a JSON array containing zero or more matches for the input provided with the request. The structure of the response is the same for both GET and POST requests.
content:
application/json:
schema:
$ref: '#/components/schemas/Results'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'402':
$ref: '#/components/responses/402'
'422':
$ref: '#/components/responses/422'
'429':
$ref: '#/components/responses/429'
'504':
$ref: '#/components/responses/504'
post:
tags:
- Lookup
summary: Search for a batch of ZIPCodes
operationId: lookup-post
description: "HTTP POST: Multiple Inputs\\n\\nA POST request allows a larger volume of data (MAX: 100 inputs or 16K per request) to be sent in the HTTP request body. In this case, the data should be encoded as a JSON array where each element in the array is a JSON object with field names identical to those in the field listing below. Here's a sample request with three inputs being sent:\n```\ncurl -v 'https://us-zipcode.api.smarty.com/lookup?\n auth-id=YOUR+AUTH-ID+HERE&\n auth-token=YOUR+AUTH-TOKEN+HERE'\n -H \"Content-Type: application/json; charset=utf-8\"\n --data-binary '\n [\n {\n \"city\":\"North Pole\",\n \"state\":\"AK\"\n },\n {\n \"zipcode\":\"12345\"\n },\n {\n \"city\":\"cupertino\",\n \"state\":\"CA\",\n \"zipcode\":\"95014\"\n }\n ]' \n```\nNote: When POSTing JSON, always make sure to add a Content-Type of application/json; charset=utf-8.\"\n"
requestBody:
description: Data should be encoded as a `JSON` array where each element in the array is a `JSON` object with field names identical to those in the provided examples.
content:
application/json; charset=utf-8:
schema:
$ref: '#/components/schemas/LookupManyArray'
required: true
responses:
'200':
description: 'OK (success!): The response body will be a JSON array containing zero or more matches for the input provided with the request. The structure of the response is the same for both GET and POST requests.'
content:
application/json; charset=utf-8:
schema:
type: array
items:
$ref: '#/components/schemas/Root'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'402':
$ref: '#/components/responses/402'
'413':
$ref: '#/components/responses/413'
'429':
$ref: '#/components/responses/429_2'
parameters:
- $ref: '#/components/parameters/Content-Type'
- $ref: '#/components/parameters/Host_3'
components:
parameters:
Host:
name: Host
in: header
required: true
schema:
type: string
description: 'The Host request header field specifies the internet host and port number of the resource being requested. Note: Most HTTP clients such as the browser, or programming language HTTP libraries will add this header automatically. Ex: Host: us-autocomplete-pro.api.smarty.com'
Referer:
name: Referer
in: header
schema:
type: string
description: 'The Referer is required when an embedded key is used for authentication. Its value is in the form of a URL, where the host component must match a host value assigned to your embedded key. Note: Some HTTP clients such as a browser or programming language HTTP libraries will add this header automatically. However some interfaces such as cURL do not, so you may need to add it manually. Ex: Referer: https://mycoolwebsite.com'
required: false
include_only_postal_code:
name: include_only_postal_code
in: query
required: false
schema:
type: string
description: 'Limit the results to only the postal codes provided. When this parameter is used, include_only_locality cannot be used. Separate multiple values with a comma. Example: 29200,29201'
max_group_results:
name: max_group_results
in: query
required: false
schema:
type: integer
description: Maximum number of address suggestions to return when expanding address groups with an Address ID; range [1, 100].
country:
name: country
in: query
required: true
schema:
type: string
description: The ISO3 Alpha-3 country code where the desired address is located. Only uppercase values are allowed. See supported country codes (https://www.smarty.com/docs/cloud/international-address-autocomplete-api#supported-country-codes). Maximum length is 3 bytes.
license:
name: license
in: query
description: The license or licenses (comma-separated) to use for this lookup. Valid values can be found in the account dashboard under the appropriate subscription. If multiple licenses are specified, they are considered in left-to-right order.
schema:
type: string
include_only_locality:
name: include_only_locality
in: query
required: false
schema:
type: string
description: 'Limit the results to only the locality provided. A locality is a significant population center (i.e. city, town, or village). When this parameter is used, include_only_postal_code cannot be used. Separate multiple values with a comma. Example: Paris,Versailles'
input_id:
name: input_id
in: query
example: 8675309
description: A unique identifier for this address used in your application; this field will be copied to the output
schema:
type: string
locality:
name: locality
in: query
example: Paris
description: The city name
schema:
type: string
search:
name: search
in: query
required: true
schema:
type: string
description: The part of the address that has already been typed. Maximum character count is 32 characters. Required when address ID is not specified in the URL.
country_2:
name: country
in: query
required: true
description: This must be entered with every address. Country Name or ISO classification (ISO-3, ISO-2, ISO-N). Address validation will fail if this is missing. (e.g. Brazil, BRA, BR, or 076)
schema:
type: string
Host_3:
name: Host
in: header
required: true
schema:
type: string
description: 'The Host request header field specifies the internet host and port number of the resource being requested. EX: Host: us-zipcode.api.smarty.com'
address_id:
name: addressId
in: path
required: true
schema:
type: string
description: The Address ID is used to get further information about a particular result. This value will be supplied by a previous call to the API. This parameter should not be supplied when the search query parameter is used.
postal_code:
name: postal_code
in: query
description: The postal code (e.g. T4B 5M7). You may submit a postal code preefix to widen your search. (e.g. T4B 5)
schema:
type: string
Content-Type:
name: Content-Type
in: header
required: true
schema:
type: string
description: 'The purpose of the Content-Type field is to describe the data contained in the body fully enough that the receiving user agent can pick an appropriate agent or mechanism to present the data to the user, or otherwise deal with the data in an appropriate manner. EX: Content-Type: application/json; charset=utf-8'
Host_2:
name: Host
in: header
required: true
schema:
type: string
description: 'The Host request header field specifies the internet host and port number of the resource being requested. EX: Host: international-postal-code.api.smarty.com'
administrative_area:
name: administrative_area
in: query
description: The state or province name or abbreviation. (e.g. Alberta or AB)
schema:
type: string
max_results:
name: max_results
in: query
required: false
schema:
type: integer
description: 'Maximum number of address suggestions to return; range [1, 10]. Default: 5'
geolocation:
name: geolocation
in: query
required: false
schema:
type: string
description: "Bias (prefer) results based on the location of the sender's IP address (IPv4 only). Valid value: on \n Supported countries: CAN, AUS, DEU. If the request to the API goes through a proxy, you will need to set an X-Forwarded-For header specifying the desired IP address for the request."
responses:
'402':
description: 'Payment Required: There is no active subscription for the account associated with the credentials submitted with the request.'
'429':
description: '''Too Many Requests: When using public embedded key authentication, we restrict the number of requests coming from a given source over too short of a time. If you use embedded key authentication, you can avoid this error by adding your IP address as an authorized host for the embedded key in question.''
''OR''
''Too Many Requests: Too many requests with exactly the same input values were submitted within too short a period. This status code conveys that the input was not processed in order to prevent runaway charges caused by such conditions as a misbehaving (infinite) loop that''s sending the same record over and over to the API. You''re welcome.''
'
'429_2':
description: 'Too Many Requests: When using public embedded key authentication, we restrict the number of requests coming from a given source over too short of a time. If you use embedded key authentication, you can avoid this error by adding your IP address as an authorized host for the embedded key in question.'
'422':
description: 'Unprocessable Entity: A GET request lacked required fields.'
'400':
description: 'Bad Request (Malformed Payload): The request body of a POST request contained no lookups or contained malformed JSON.'
detailed_200:
description: 'OK (success!): The response body is a JSON object with a candidates array containing candidates based on the supplied input parameters.'
content:
application/json:
schema:
type: object
properties:
candidates:
type: array
items:
$ref: '#/components/schemas/detailed_candidate'
'413':
description: 'Request Entity Too Large: The maximum size for a request body to this API is 16K (16,384 bytes).'
'200':
description: 'OK (success!): The response body is a JSON object with a candidates array containing candidates based on the supplied input parameters.'
content:
application/json:
schema:
type: object
properties:
candidates:
type: array
items:
$ref: '#/components/schemas/candidate'
'504':
description: 'Gateway Timeout: Our own upstream data provider did not repond in a timely fashion, and the request failed. A serious, yet rare occurrence indeed.'
'401':
description: 'Unauthorized: The credentials were provided incorrectly or did not match any existing, active credentials.'
schemas:
detailed_candidate:
title: detailed_candidate
type: object
properties:
street:
type: string
locality:
type: string
administrative_area:
type: string
administrative_area_short:
type: string
administrative_area_long:
type: string
postal_code:
type: string
country_iso3:
type: string
examples:
- street: 1-123 Main St
locality: Fredericton
administrative_area: NB
administrative_area_short: NB
administrative_area_long: New Brunswick
postal_code: E3A 1C7
country_iso3: CAN
Results:
title: Successful response
type: object
description: 'OK (success!): The response body will be a JSON array containing 0 to 1000 items for the input provided with the request. Since there is no paging capability to return more than the maximum, you will need to refine your search to return fewer results. Transliteration is not available in this API. All results will be returned using the Latin character set.'
properties:
input_id:
type: string
description: A unique identifier generated by you for this address for use within your application. The output will be identical to the value you provided in the request input_id.
administrative_area:
type: string
description: The most common administrative division within a country (ex. province in Canada)
super_administrative_area:
type: string
description: The largest administrative division within a country (ex. region in France)
sub_administrative_area:
type: string
description: The smallest administrative division within a country (ex. county in Germany)
locality:
type: string
description: Within a country, this is the most common population center (ex. city in Chile)
dependent_locality:
type: string
description: If there is additional information about the locality, it will be here (ex. neighborhood in Turkey)
dependent_locality_name:
type: string
description: If the dependent_locality has a name, you'll find it here. (ex. the dependent_locality 'Dong Cheng Qu' is named 'Dong Cheng')
double_dependent_locality:
type: string
description: If there is additional information about the dependent_locality, you'll find it here. (ex. village in the United Kingdom)
postal_code:
type: string
description: The complete postal code for the delivery point (ex. V6G1V9 in Canada)
postal_code_extra:
type: string
description: Secondary postal code information (ex. 3425 in the United States)
country_iso_3:
type: string
description: The ISO 3166-1 alpha-3 country code
CityStates:
title: CityStates
type: object
properties:
city:
type: string
example: Provo
description: The name of a city
state_abbreviation:
type: string
example: UT
description: The official, two-letter state abbreviation
state:
type: string
example: Utah
description: The state name
mailable_city:
type: boolean
description: A boolean value indicating whether or not the city name is an approved USPS mailing name
LookupManyArray:
type: string
ZIPCodes:
title: ZIPCodes
type: object
properties:
zipcode:
type: string
example: '84604'
description: The 5 digit ZIP code
zipcode_type:
type: string
example: S
description: 'The type of ZIP Code. Possible values:
S - Standard (regular ZIP Code)
M - Military (APO/FPO military ZIP Code. Also includes DPO - Diplomatic addresses)
P - P.O. Box (serves only post-office boxes)
U - Unique (belongs primarily to a firm)'
default_city:
type: string
example: Provo
description: A string containing the default city name for this ZIP Code
county_fips:
type: string
example: '49049'
description: The county FIPS Code
county_name:
type: string
example: Utah
description: 'The name of the county in which the ZIP Code is located
Note: The county name listed here pertains to the 5-digit ZIP Code, not necessarily the city.'
state_abbreviation:
type: string
example: UT
description: The official, two-letter state abbreviation
state:
type: string
example: Utah
description: The state name
latitude:
type: number
example: 40.26763
description: The approximate latitude geo-coordinate
longitude:
type: number
example: -111.65763
description: The approximate longitude geo-coordinate
precision:
type: string
example: Zip5
description: "Indicates the precision of the latitude and longitude values. \n\nNone — Coordinates not known. Reasons could include: address is invalid, military address (APO or FPO), lat/lon coordinates not available.\nZip5 — Accurate to a 5-digit ZIP Code level (least precise)\nZip6 — Accurate to a 6-digit ZIP Code level\nZip7 — Accurate to a 7-digit ZIP Code level\nZip8 — Accurate to an 8-digit ZIP Code level\nZip9 — Accurate to a 9-digit ZIP Code level (most precise but NOT rooftop level)"
alternate_counties:
type: array
description: 'The county FIPS codes, county names, state abbreviations, and states, that share the same ZIP Code. Note: The county names listed here pertain to the 5-digit ZIP Code, not necessarily the city.'
items:
$ref: '#/components/schemas/AlternateCounties'
AlternateCounties:
title: AlternateCounties
type: object
properties:
county_fips:
type: string
example: '49051'
description: The county FIPS Code
county_name:
type: string
example: Utah
description: 'The name of the county in which the ZIP Code is located
Note: The county name listed here pertains to the 5-digit ZIP Code, not necessarily the city.'
state_abbreviation:
type: string
example: UT
description: The official, two-letter state abbreviation
state:
type: string
example: Utah
description: The state name
description: 'The county FIPS codes, county names, state abbreviations, and states, that share the same ZIP Code. Note: The county names listed here pertain to the 5-digit ZIP Code, not necessarily the city.
'
Root:
title: Successful response
type: object
description: 'OK (success!): The response body will be a JSON array containing zero or more matches for the input provided with the request. The structure of the response is the same for both GET and POST requests.'
properties:
input_index:
type: integer
input_id:
type: string
description: A unique identifier for this address used in your application; this field will be copied into the output.
city_states:
type: array
description: A list of cities and their states that match the input
items:
$ref: '#/components/schemas/CityStates'
zipcodes:
type: array
description: A list of ZIP Codes that match the input
items:
$ref: '#/components/schemas/ZIPCodes'
status:
type: string
description: For a lookup with no matches, status classifies the kind of failure and always comes with a reason
reason:
type: string
description: "For a lookup with no matches, reason explains why the lookup failed\n\nblank\tBlank lookup (you must provide a ZIP Code and/or City/State combination).\ninvalid_state\tInvalid State name or abbreviation.\ninvalid_city\tInvalid City for the given State.\ninvalid_zipcode\tInvalid ZIP Code.\nconflict\tConflicting ZIP Code/City/State information."
candidate:
title: candidate
type: object
properties:
entries:
type: integer
address_text:
type: string
address_id:
type: string
examples:
- entries: 12
address_text: 123 Main St Winnipeg, MB, R3C
address_id: PD4DPC8DOjE4AzI9Uig2MTE2Lzo4UjI+NjEgLCtSTk1M
securitySchemes:
auth-id:
type: apiKey
name: auth-id
in: query
auth-token:
type: apiKey
name: auth-token
in: query
embedded-key:
type: apiKey
name: key
in: query
externalDocs:
description: Extensive documentation for the International Address Autocomplete API
url: https://www.smarty.com/docs/cloud/international-address-autocomplete-api