openapi: 3.0.1
info:
  title: Geocodio 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: Forward Geocoding
    description: Convert addresses into coordinates.
  - name: Reverse Geocoding
    description: Convert coordinates into addresses.
  - name: Batch
    description: Geocode or reverse geocode up to 10,000 records per request.
  - name: Lists
    description: Asynchronous spreadsheet geocoding jobs.
paths:
  /geocode:
    get:
      operationId: geocode
      tags:
        - Forward Geocoding
      summary: Geocode a single address
      description: >-
        Converts a single address into latitude and longitude. Provide a full
        address with the q parameter, or supply individual address components.
      parameters:
        - name: q
          in: query
          description: A full address to geocode, e.g. "1109 N Highland St, Arlington VA".
          required: false
          schema:
            type: string
        - name: street
          in: query
          required: false
          schema:
            type: string
        - name: city
          in: query
          required: false
          schema:
            type: string
        - name: state
          in: query
          required: false
          schema:
            type: string
        - name: postal_code
          in: query
          required: false
          schema:
            type: string
        - name: country
          in: query
          required: false
          schema:
            type: string
        - name: fields
          in: query
          description: Comma-separated list of data append fields, e.g. "cd,stateleg,census,timezone". Each field counts as an additional lookup.
          required: false
          schema:
            type: string
        - name: limit
          in: query
          description: Maximum number of results to return.
          required: false
          schema:
            type: integer
        - name: format
          in: query
          description: Set to "simple" for a streamlined response.
          required: false
          schema:
            type: string
            enum: [simple]
      responses:
        '200':
          description: A geocoding result set.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeocodeResponse'
        '422':
          description: Could not geocode the supplied address.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      operationId: batchGeocode
      tags:
        - Batch
      summary: Batch geocode addresses
      description: >-
        Geocodes up to 10,000 addresses in a single request. The body may be a
        JSON array of address strings or a JSON object keyed by your own
        identifiers.
      parameters:
        - name: fields
          in: query
          required: false
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchGeocodeRequest'
      responses:
        '200':
          description: A batch geocoding result set.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchGeocodeResponse'
  /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'
    post:
      operationId: batchReverse
      tags:
        - Batch
      summary: Batch reverse geocode coordinates
      description: >-
        Reverse geocodes up to 10,000 coordinate pairs in a single request. The
        body may be a JSON array of "lat,lng" strings or a JSON object keyed by
        your own identifiers.
      parameters:
        - name: fields
          in: query
          required: false
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchReverseRequest'
      responses:
        '200':
          description: A batch reverse geocoding result set.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchGeocodeResponse'
  /lists:
    get:
      operationId: listLists
      tags:
        - Lists
      summary: View all lists
      description: Returns all spreadsheet geocoding list jobs for the account.
      responses:
        '200':
          description: A paginated set of list jobs.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListCollection'
    post:
      operationId: createList
      tags:
        - Lists
      summary: Create a list
      description: >-
        Uploads a spreadsheet file (CSV, TSV, Excel) to be geocoded
        asynchronously as a list job.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/CreateListRequest'
      responses:
        '200':
          description: The created list job.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/List'
  /lists/{id}:
    get:
      operationId: getList
      tags:
        - Lists
      summary: Check list status
      description: Returns the status and metadata for a single list job.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: The list job.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/List'
        '404':
          description: List not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      operationId: deleteList
      tags:
        - Lists
      summary: Delete a list
      description: Deletes a list job and its stored results.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Deletion confirmation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteResponse'
  /lists/{id}/download:
    get:
      operationId: downloadList
      tags:
        - Lists
      summary: Download list results
      description: Downloads the completed, geocoded spreadsheet for a list job.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: The geocoded spreadsheet file.
          content:
            text/csv:
              schema:
                type: string
                format: binary
components:
  securitySchemes:
    apiKeyQuery:
      type: apiKey
      in: query
      name: api_key
      description: Geocodio API key passed as the api_key query parameter.
  schemas:
    GeocodeResponse:
      type: object
      properties:
        input:
          $ref: '#/components/schemas/Input'
        results:
          type: array
          items:
            $ref: '#/components/schemas/Result'
    Input:
      type: object
      properties:
        address_components:
          $ref: '#/components/schemas/AddressComponents'
        formatted_address:
          type: string
    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
    BatchGeocodeRequest:
      oneOf:
        - type: array
          items:
            type: string
          example:
            - 1109 N Highland St, Arlington VA
            - 525 University Ave, Toronto, ON, Canada
        - type: object
          additionalProperties:
            type: string
          example:
            '1': 1109 N Highland St, Arlington VA
            '2': 525 University Ave, Toronto, ON, Canada
    BatchReverseRequest:
      oneOf:
        - type: array
          items:
            type: string
          example:
            - 35.9746000,-77.9658000
            - 32.8793000,-96.6300000
        - type: object
          additionalProperties:
            type: string
    BatchGeocodeResponse:
      type: object
      properties:
        results:
          type: array
          items:
            type: object
            properties:
              query:
                type: string
              response:
                $ref: '#/components/schemas/GeocodeResponse'
    CreateListRequest:
      type: object
      properties:
        file:
          type: string
          format: binary
          description: The spreadsheet file to geocode (CSV, TSV, or Excel).
        direction:
          type: string
          enum: [forward, reverse]
          description: Whether to forward or reverse geocode the list.
        format:
          type: string
          description: Column template, e.g. "{{A}} {{B}} {{C}} {{D}}".
        callback:
          type: string
          description: Optional webhook URL called when processing completes.
        fields:
          type: string
          description: Comma-separated data append fields.
      required:
        - direction
        - format
    List:
      type: object
      properties:
        id:
          type: integer
          example: 1234
        file:
          type: object
          properties:
            headers:
              type: array
              items:
                type: string
            estimated_rows_count:
              type: integer
            filename:
              type: string
        status:
          type: object
          properties:
            state:
              type: string
              example: PROCESSING
            progress:
              type: integer
            message:
              type: string
            time_left_description:
              type: string
            download_url:
              type: string
        download_url:
          type: string
        expires_at:
          type: string
          format: date-time
        created_at:
          type: string
          format: date-time
    ListCollection:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/List'
        meta:
          type: object
          additionalProperties: true
    DeleteResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
    Error:
      type: object
      properties:
        error:
          type: string
          example: Could not geocode address. Postal code or city required.