openapi: 3.0.1
info:
  title: Geocodio Batch Reverse Geocoding API
  description: Geocodio is a US and Canada geocoding API for forward geocoding (address to coordinates), reverse geocoding (coordinates to address), batch geocoding of up to 10,000 records, asynchronous spreadsheet list jobs, and data appends that enrich results with congressional districts, state legislative districts, census geographies, ACS demographics, school districts, ZIP+4, timezone, and Canadian electoral data. Requests are authenticated with an api_key query parameter and the first 2,500 lookups per day are free.
  termsOfService: https://www.geocod.io/terms-of-service/
  contact:
    name: Geocodio Support
    email: support@geocod.io
    url: https://www.geocod.io/contact/
  version: '1.7'
servers:
- url: https://api.geocod.io/v1.7
  description: Geocodio API v1.7
security:
- apiKeyQuery: []
tags:
- name: Reverse Geocoding
  description: Convert coordinates into addresses.
paths:
  /reverse:
    get:
      operationId: reverse
      tags:
      - Reverse Geocoding
      summary: Reverse geocode a single coordinate
      description: Converts a single latitude,longitude pair into the nearest street address.
      parameters:
      - name: q
        in: query
        description: A latitude,longitude pair, e.g. "38.9002898,-76.9990361".
        required: true
        schema:
          type: string
      - name: fields
        in: query
        required: false
        schema:
          type: string
      - name: limit
        in: query
        required: false
        schema:
          type: integer
      - name: format
        in: query
        required: false
        schema:
          type: string
          enum:
          - simple
      responses:
        '200':
          description: A reverse geocoding result set.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeocodeResponse'
        '422':
          description: Could not reverse geocode the supplied coordinate.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Result:
      type: object
      properties:
        address_components:
          $ref: '#/components/schemas/AddressComponents'
        formatted_address:
          type: string
          example: 1109 N Highland St, Arlington, VA 22201
        location:
          $ref: '#/components/schemas/Location'
        accuracy:
          type: number
          format: float
          description: Accuracy score between 0 and 1.
          example: 1
        accuracy_type:
          type: string
          description: How the match was determined.
          example: rooftop
        source:
          type: string
          example: Virginia GIS Clearinghouse
        fields:
          type: object
          description: Appended data fields when requested via the fields parameter.
          additionalProperties: true
    AddressComponents:
      type: object
      properties:
        number:
          type: string
          example: '1109'
        predirectional:
          type: string
          example: N
        street:
          type: string
          example: Highland
        suffix:
          type: string
          example: St
        formatted_street:
          type: string
          example: N Highland St
        city:
          type: string
          example: Arlington
        county:
          type: string
          example: Arlington County
        state:
          type: string
          example: VA
        zip:
          type: string
          example: '22201'
        country:
          type: string
          example: US
    Location:
      type: object
      properties:
        lat:
          type: number
          format: double
          example: 38.886665
        lng:
          type: number
          format: double
          example: -77.094733
    Error:
      type: object
      properties:
        error:
          type: string
          example: Could not geocode address. Postal code or city required.
    Input:
      type: object
      properties:
        address_components:
          $ref: '#/components/schemas/AddressComponents'
        formatted_address:
          type: string
    GeocodeResponse:
      type: object
      properties:
        input:
          $ref: '#/components/schemas/Input'
        results:
          type: array
          items:
            $ref: '#/components/schemas/Result'
  securitySchemes:
    apiKeyQuery:
      type: apiKey
      in: query
      name: api_key
      description: Geocodio API key passed as the api_key query parameter.