# https://swagger.io/docs/specification/about/ openapi: "3.0.3" info: version: 2.0.0 title: Addressable description: A simple RESTful JSON web API that allows website, web and desktop application developers to easily implement address verification, geocoding and autocomplete for Australia, Canada, Denmark, Estonia, Finland, Faroe Islands, Greenland, Iceland, Lithuania, Latvia, Norway, New Zealand, and Sweden contact: name: API Support email: support@addressable.dev url: https://www.addressable.dev license: name: License url: https://www.addressable.dev/pages/terms termsOfService: https://www.addressable.dev/pages/terms servers: - url: https://api.addressable.dev paths: /v2/autocomplete: get: tags: ["address"] description: | Lookup possible addresses that match the partial address query value. 4-6 numbers and characters is typically enough to identify an address. operationId: autocomplete parameters: - name: q in: query description: The address query string. Can be a partial address required: true schema: type: string example: "220 Queen St Auc" - name: country_code in: query description: "The ISO 3166 Country Code" required: true schema: type: string enum: - AU - CA - DK - EE - FI - FO - GL - IS - LT - LV - NO - NZ - SE - name: type in: query description: | A comma separated list of field types. Accepted: [number, street, locality]. Filters results to include only the types specified. Example usage: use the "street" filter to only include one result for each street, and exclude street-number-granularity results. Example usage: use the "locality" filter when running autocomplete for a suburb form field to exclude street or number results. Default will search all field types. required: false schema: type: string default: "number, street, locality" - name: max_results in: query description: "Maximum number of results to return. Must be an integer from 1 to 10." required: false schema: type: integer minimum: 1 maximum: 10 default: 5 responses: '200': description: An array of matching address objects content: application/json: schema: type: array items: oneOf: - $ref: '#/components/schemas/AddressAU' - $ref: '#/components/schemas/AddressCA' - $ref: '#/components/schemas/AddressDK' - $ref: '#/components/schemas/AddressEE' - $ref: '#/components/schemas/AddressFI' - $ref: '#/components/schemas/AddressFO' - $ref: '#/components/schemas/AddressGL' - $ref: '#/components/schemas/AddressIS' - $ref: '#/components/schemas/AddressLT' - $ref: '#/components/schemas/AddressLV' - $ref: '#/components/schemas/AddressNO' - $ref: '#/components/schemas/AddressNZ' - $ref: '#/components/schemas/AddressSE' '400': $ref: "#/components/responses/BadRequestError" '401': $ref: "#/components/responses/UnauthorizedError" '406': $ref: "#/components/responses/NotAcceptableError" '429': $ref: "#/components/responses/RateLimitedError" /v2/reverse: get: tags: ["address"] description: | Convert geographic coordinates into a human-readable address or place name operationId: reverse parameters: - name: lat in: query description: The latitude of the location to reverse geocode required: true schema: type: number example: -36.849304 minimum: -90 maximum: 90 - name: lon in: query description: The longitude of the location to reverse geocode required: true schema: type: number example: 174.765469 minimum: -180 maximum: 180 responses: '200': description: An array of matching address objects content: application/json: schema: type: array items: oneOf: - allOf: - $ref: '#/components/schemas/AddressAU' - type: object properties: country_code: type: string example: "AU" - allOf: - $ref: '#/components/schemas/AddressCA' - type: object properties: country_code: type: string example: "CA" - allOf: - $ref: '#/components/schemas/AddressDK' - type: object properties: country_code: type: string example: "DK" - allOf: - $ref: '#/components/schemas/AddressEE' - type: object properties: country_code: type: string example: "EE" - allOf: - $ref: '#/components/schemas/AddressFI' - type: object properties: country_code: type: string example: "FI" - allOf: - $ref: '#/components/schemas/AddressFO' - type: object properties: country_code: type: string example: "FO" - allOf: - $ref: '#/components/schemas/AddressGL' - type: object properties: country_code: type: string example: "GL" - allOf: - $ref: '#/components/schemas/AddressIS' - type: object properties: country_code: type: string example: "IS" - allOf: - $ref: '#/components/schemas/AddressLT' - type: object properties: country_code: type: string example: "LT" - allOf: - $ref: '#/components/schemas/AddressLV' - type: object properties: country_code: type: string example: "LV" - allOf: - $ref: '#/components/schemas/AddressNO' - type: object properties: country_code: type: string example: "NO" - allOf: - $ref: '#/components/schemas/AddressNZ' - type: object properties: country_code: type: string example: "NZ" - allOf: - $ref: '#/components/schemas/AddressSE' - type: object properties: country_code: type: string example: "SE" '401': $ref: "#/components/responses/UnauthorizedError" '406': $ref: "#/components/responses/NotAcceptableError" '429': $ref: "#/components/responses/RateLimitedError" /v2/profile: get: tags: ["profile"] description: | Check identity or subscription expiry operationId: profile responses: '200': description: The user profile object content: application/json: schema: type: object properties: email: type: string format: email subscription_expires_on: type: string format: date '401': $ref: "#/components/responses/UnauthorizedError" '429': $ref: "#/components/responses/RateLimitedError" components: schemas: AddressAU: type: object properties: building_name: type: string nullable: true unit_details: type: string nullable: true street_number: type: string nullable: true street: type: string nullable: true locality: type: string nullable: true region: type: string nullable: true postcode: type: string nullable: true meshblock: type: string nullable: true lon: type: string nullable: true lat: type: string nullable: true formatted: type: string AddressCA: type: object properties: street_number: type: string nullable: true street: type: string nullable: true locality: type: string nullable: true city: type: string nullable: true region: type: string nullable: true postcode: type: string nullable: true lon: type: string nullable: true lat: type: string nullable: true formatted: type: string AddressDK: type: object properties: street_number: type: string nullable: true street: type: string nullable: true locality: type: string nullable: true postcode: type: string nullable: true region: type: string nullable: true municipality: type: string nullable: true lon: type: string nullable: true lat: type: string nullable: true formatted: type: string AddressEE: type: object properties: street_number: type: string nullable: true street: type: string nullable: true locality: type: string nullable: true postcode: type: string nullable: true district: type: string nullable: true municipality: type: string nullable: true lon: type: string nullable: true lat: type: string nullable: true formatted: type: string AddressFI: type: object properties: street_number: type: string nullable: true street: type: string nullable: true locality: type: string nullable: true postcode: type: string nullable: true municipality: type: string nullable: true lon: type: string nullable: true lat: type: string nullable: true formatted: type: string AddressFO: type: object properties: street_number: type: string nullable: true street: type: string nullable: true locality: type: string nullable: true postcode: type: string nullable: true region: type: string nullable: true municipality: type: string nullable: true lon: type: string nullable: true lat: type: string nullable: true formatted: type: string AddressGL: type: object properties: street_number: type: string nullable: true street: type: string nullable: true locality: type: string nullable: true postcode: type: string nullable: true region: type: string nullable: true municipality: type: string nullable: true lon: type: string nullable: true lat: type: string nullable: true formatted: type: string AddressIS: type: object properties: street_number: type: string nullable: true street: type: string nullable: true locality: type: string nullable: true postcode: type: string nullable: true region: type: string nullable: true municipality: type: string nullable: true lon: type: string nullable: true lat: type: string nullable: true formatted: type: string AddressLT: type: object properties: street_number: type: string nullable: true street: type: string nullable: true locality: type: string nullable: true postcode: type: string nullable: true region: type: string nullable: true municipality: type: string nullable: true lon: type: string nullable: true lat: type: string nullable: true formatted: type: string AddressLV: type: object properties: street_number: type: string nullable: true street: type: string nullable: true locality: type: string nullable: true postcode: type: string nullable: true region: type: string nullable: true municipality: type: string nullable: true lon: type: string nullable: true lat: type: string nullable: true formatted: type: string AddressNO: type: object properties: street_number: type: string nullable: true street: type: string nullable: true locality: type: string nullable: true postcode: type: string nullable: true region: type: string nullable: true municipality: type: string nullable: true lon: type: string nullable: true lat: type: string nullable: true formatted: type: string AddressNZ: type: object properties: street_number: type: string nullable: true street: type: string nullable: true locality: type: string nullable: true city: type: string nullable: true region: type: string nullable: true postcode: type: string nullable: true meshblock: type: string nullable: true lon: type: string nullable: true lat: type: string nullable: true formatted: type: string AddressSE: type: object properties: street_number: type: string nullable: true street: type: string nullable: true locality: type: string nullable: true postcode: type: string nullable: true district: type: string nullable: true municipality: type: string nullable: true lon: type: string nullable: true lat: type: string nullable: true formatted: type: string securitySchemes: ApiKeyAuth: type: apiKey name: api_key in: query responses: BadRequestError: description: Required query parameter is missing UnauthorizedError: description: API key is missing or invalid NotAcceptableError: description: Invalid query parameter values RateLimitedError: description: Rate limit exceeded security: - ApiKeyAuth: []