Placekey Bulk Lookup API

openapi: 3.0.1
info:
  title: Placekey API
  description: >-
    The Placekey API resolves an address, point-of-interest, or
    latitude/longitude coordinate pair into a Placekey - a free, universal
    identifier for any physical place. It supports single lookups (POST
    /placekey) and bulk lookups of up to 100 queries per request (POST
    /placekeys). Authentication is via the apikey request header.
  termsOfService: https://www.placekey.io/terms-conditions
  contact:
    name: Placekey Support
    url: https://www.placekey.io/contact
  version: '1.0'
servers:
  - url: https://api.placekey.io/v1
    description: Placekey API v1
security:
  - apiKey: []
paths:
  /placekey:
    post:
      operationId: lookupPlacekey
      tags:
        - Lookup
      summary: Look up a single Placekey
      description: >-
        Resolves a single query (address, POI, and/or latitude/longitude) into
        a Placekey. At minimum a latitude/longitude pair or a street address
        with sufficient locality information should be supplied.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SingleLookupRequest'
            examples:
              coordinates:
                summary: Lookup by latitude/longitude
                value:
                  query:
                    latitude: 37.7371
                    longitude: -122.44283
              address:
                summary: Lookup by address and POI
                value:
                  query:
                    location_name: Twin Peaks Petite Restaurant
                    street_address: 598 Portola Dr
                    city: San Francisco
                    region: CA
                    postal_code: '94131'
                    iso_country_code: US
      responses:
        '200':
          description: A single Placekey result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlacekeyResult'
        '400':
          description: Bad request - malformed query.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - missing or invalid apikey.
        '429':
          description: Too Many Requests - rate limit exceeded.
  /placekeys:
    post:
      operationId: lookupPlacekeysBulk
      tags:
        - Bulk
      summary: Look up Placekeys in bulk
      description: >-
        Resolves up to 100 queries in a single request. Each query may include
        an optional query_id that is echoed back in the response. All queries in
        a batch must share the same iso_country_code.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkLookupRequest'
            example:
              queries:
                - query_id: '0'
                  street_address: 1543 Mission Street, Floor 3
                  city: San Francisco
                  region: CA
                  postal_code: '94105'
                  iso_country_code: US
                - query_id: '1'
                  latitude: 37.7371
                  longitude: -122.44283
                  iso_country_code: US
      responses:
        '200':
          description: A list of Placekey results, one per query.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PlacekeyResult'
        '400':
          description: Bad request - batch exceeds 100 queries or queries are malformed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - missing or invalid apikey.
        '429':
          description: Too Many Requests - rate limit exceeded.
components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: apikey
      description: Placekey API key supplied in the apikey request header.
  schemas:
    Query:
      type: object
      description: >-
        A location query. Provide a latitude/longitude pair and/or address
        components. Including more fields generally improves match quality.
      properties:
        query_id:
          type: string
          description: >-
            Optional client-supplied identifier echoed back in the response. If
            omitted in bulk requests, sequential identifiers (0, 1, 2, ...) are
            generated.
        latitude:
          type: number
          format: double
          description: Latitude in decimal degrees.
        longitude:
          type: number
          format: double
          description: Longitude in decimal degrees.
        location_name:
          type: string
          description: The name of the place or point of interest.
        street_address:
          type: string
          description: The street address of the place.
        city:
          type: string
          description: The city the place is in.
        region:
          type: string
          description: The state, province, or region the place is in.
        postal_code:
          type: string
          description: The postal or ZIP code of the place.
        iso_country_code:
          type: string
          description: Two-character ISO 3166-1 alpha-2 country code (e.g. US).
        place_metadata:
          $ref: '#/components/schemas/PlaceMetadata'
    PlaceMetadata:
      type: object
      description: Optional additional metadata used to improve POI matching.
      properties:
        store_id:
          type: string
          description: A client-specific store identifier.
        phone_number:
          type: string
          description: The phone number of the place.
        website:
          type: string
          description: The website of the place.
        naics_code:
          type: string
          description: The NAICS industry code for the place.
        mcc_code:
          type: string
          description: The merchant category code for the place.
    SingleLookupRequest:
      type: object
      required:
        - query
      properties:
        query:
          $ref: '#/components/schemas/Query'
        options:
          $ref: '#/components/schemas/Options'
    BulkLookupRequest:
      type: object
      required:
        - queries
      properties:
        queries:
          type: array
          maxItems: 100
          description: An array of up to 100 location queries.
          items:
            $ref: '#/components/schemas/Query'
        options:
          $ref: '#/components/schemas/Options'
    Options:
      type: object
      description: Options applied to all queries in the request.
      properties:
        strict_address_match:
          type: boolean
          description: >-
            When true, only return a Placekey if the address matches exactly.
        strict_name_match:
          type: boolean
          description: >-
            When true, only return a Placekey if the location_name matches
            exactly.
        fields:
          type: array
          description: >-
            Additional response fields to return beyond query_id and placekey.
          items:
            type: string
    PlacekeyResult:
      type: object
      properties:
        query_id:
          type: string
          description: >-
            The identifier for this query, echoed back if supplied, otherwise a
            generated sequential value.
        placekey:
          type: string
          description: >-
            The Placekey identifier for the resolved place (e.g.
            227-223@5vg-82n-pgk).
        error:
          type: string
          description: >-
            Present instead of placekey when the query could not be matched.
      example:
        query_id: '0'
        placekey: 227-223@5vg-82n-pgk
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: A human-readable error message.