# 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, Estonia, 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 - EE - 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/AddressEE' - $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/AddressEE' - type: object properties: country_code: type: string example: "EE" - 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 region: type: string nullable: true postcode: 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 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: []