openapi: 3.0.1
info:
  title: International Address Autocomplete Lookup reverse-geo 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: reverse-geo
  description: Operation invlovling reverse geocoding
paths:
  /lookup:
    parameters: []
    get:
      summary: Convert Coordinates to Nearest Addresses
      tags:
      - reverse-geo
      responses:
        '200':
          $ref: '#/components/responses/ReverseGeoValidResponse'
        '400':
          description: Bad Request, The request body was blank or otherwise malformed.
        '401':
          description: Unauthorized, The credentials were provided incorrectly or did not match any existing, active credentials.
        '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. 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.
      operationId: get-street-address
      parameters:
      - schema:
          type: string
        in: header
        name: Host
        required: true
        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.'
      - schema:
          type: string
        in: header
        name: Referer
        required: false
        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.'
      - schema:
          type: number
        in: query
        name: latitude
        required: true
        description: Latitude portion of the coordinate. The latitude must be specified as a decimal between -90.0 and 90.0
      - schema:
          type: number
        in: query
        name: longitude
        required: true
        description: Longitude portion of the coordinate. The longitude must be specified as a decimal between -180.0 and 180.0
      - schema:
          type: string
        in: query
        name: source
        required: false
        description: 'Includes all results from alternate data sources. Allowed values are: all - will include non-postal addresses in the results; postal - will limit the results to postal addresses only. If this parameter is used, an additional field named soruce will be returned for each result. Default: postal'
      description: This api runs Smarty's reverse geocoding algorithms to convert latitudinal and longitudinal coordinates into the closest street addresses at lightning speed! Enter your auth-id and auth-token or just a Smarty embedded-key along with your coordinates and you are off!
      security:
      - auth-id: []
        auth-token: []
      - embedded-key: []
components:
  schemas:
    Coordinate:
      type: object
      examples:
      - latitude: 40.202583
        longitude: -111.62196
        accuracy: Rooftop
        license: 1
      title: Coordinate
      description: Object containing basic coordinate information
      properties:
        latitude:
          type: number
          description: 'Type: Decimal


            Info: The latitude value of this address.'
        longitude:
          type: number
          description: 'Type: Decimal


            Info: The longitude value of this address.'
        accuracy:
          type: string
          maxLength: 18
          description: "Type: varchar(18)\n\nInfo: Indicates the accuracy of the latitude and longitude values. \n\nUnknown — Coordinates not known. Reasons could include: lat/lon coordinates not available.\nZip5 — Accurate to a 5-digit ZIP Code level (least accurate)\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\nParcel — Accurate to the centroid of a property parcel.\nRooftop — Accurate to the rooftop of a structure for this address.\n\nNote: Concerning addresses for which the ZIP9 accuracy is not available, the ZIP# accuracy is interpolated based on neighboring addresses. Thus, ZIP7 is an average of all the lat/long coordinates of nearby ZIP Codes that share those first 7 digits."
        license:
          type: integer
          description: 'Type: int


            Info: The license ID for the geographic coordinate returned. See the licensing table at https://www.smarty.com/docs/cloud/us-reverse-geo-api for more details'
      required:
      - latitude
      - longitude
      - license
    Address:
      type: object
      examples:
      - street: 1476 Sandhill Rd
        city: Orem
        state_abbreviation: UT
        zipcode: '84058'
      title: Address
      description: Object containing basic address information
      properties:
        street:
          type: string
          maxLength: 64
          description: varchar(64) The street name of this address.
        city:
          type: string
          maxLength: 64
          description: varchar(64) The city name of this address.
        state_abbreviation:
          type: string
          maxLength: 2
          description: varchar(2) The state abbreviation of this address.
        zipcode:
          type: string
          maxLength: 5
          description: varchar(5) The 5-digit ZIP Code of this address.
        source:
          type: string
          maxLength: 6
          description: This field is only returned if the request contained the source parameter. When it is returned, it indicates the data source for this address. Postal - the address is deliverable by the USPS. Other - the address was obtained from an alternate source (non-postal).
        smarty_key:
          type: string
          maxLength: 10
          description: Smarty's unique identifier for an address
      required:
      - Street
      - city
      - state_abbreviation
      - zipcode
      - smarty_key
    Result:
      title: Result
      type: array
      maxLength: 10
      items:
        type: object
        properties:
          coordinate:
            $ref: '#/components/schemas/Coordinate'
            description: Coordinate object containing basic coordinate information
          distance:
            type: number
            examples:
            - 34.95276
            description: The distance in meters of this address to the input latitude/longitude values.
          address:
            $ref: '#/components/schemas/Address'
            description: Address object containing basic address information
        required:
        - address
        - coordinate
  responses:
    ReverseGeoValidResponse:
      description: Valid reverse geocoding response containing the results of the search. Each object in the results list will contain an Address object, Coordinate object, and an optional distance field. The distance field is left blank where there is an exact match.
      content:
        application/json:
          schema:
            type: object
            properties:
              results:
                $ref: '#/components/schemas/Result'
                description: The array of result objects. Each object contains a coordinate object, a distance, and an address object.
            required:
            - results
  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