International Address Autocomplete API

openapi: 3.0.1
info:
  title: International Address Autocomplete
  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: [email protected]
servers:
  - url: 'https://international-autocomplete.api.smarty.com'
externalDocs:
  description: Extensive documentation for the International Address Autocomplete API
  url: 'https://www.smarty.com/docs/cloud/international-address-autocomplete-api'
paths:
  /v2/lookup:
    get:
      summary: Get Autocomplete Suggestions
      tags: []
      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: [ ]
      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'
components:
  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
    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
  responses:
    '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'
    '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'
  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
    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.'
    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.'
    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.'
    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'
    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].'
    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."
    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'
    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'