openapi: 3.0.3
info:
  title: LocaCloud API
  description: >-
    Geospatial and demographic API for U.S. states, counties, cities, and ZIP
    codes.
  version: 1.0.0
servers:
  - url: https://api.locacloud.com
components:
  parameters:
    limit:
      name: limit
      in: query
      description: Number of results to return
      required: false
      schema:
        type: integer
        default: 100
    offset:
      name: offset
      in: query
      description: Number of results to skip
      required: false
      schema:
        type: integer
        default: 0
    sortBy:
      name: sortBy
      in: query
      description: Field to sort by (use `-` for descending)
      required: false
      schema:
        type: string
        example: NAME or -NAME
    fields:
      name: fields
      in: query
      description: Comma-separated list of properties to include
      required: false
      schema:
        type: string
        example: NAME,STUSPS
    includeGeometry:
      name: includeGeometry
      in: query
      description: Include GeoJSON geometry in the response
      required: false
      schema:
        type: boolean
        default: false
    filters:
      name: filters
      in: query
      description: Filters (key:value,key:value) or JSON
      required: false
      schema:
        type: string
        example: REGION:3 or {"REGION":3}
paths:
  /api/states:
    get:
      summary: Get a list of U.S. states
      description: >-
        Returns a list of U.S. states with optional filters, sorting, field
        selection, and pagination.
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/sortBy'
        - $ref: '#/components/parameters/fields'
        - $ref: '#/components/parameters/includeGeometry'
        - $ref: '#/components/parameters/filters'
      responses:
        '200':
          description: A paginated list of states
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        _id:
                          type: string
                        properties:
                          type: object
                          example:
                            NAME: California
                            STUSPS: CA
                  totalCount:
                    type: integer
                  limit:
                    type: integer
                  offset:
                    type: integer
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '429':
          description: Too Many Requests
        '500':
          description: Internal server error
        '504':
          description: Gateway Timeout
  /api/counties:
    get:
      summary: Get a list of U.S. counties
      description: >-
        Returns a list of counties with optional filters, sorting, field
        selection, and pagination.
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/sortBy'
        - $ref: '#/components/parameters/fields'
        - $ref: '#/components/parameters/includeGeometry'
        - $ref: '#/components/parameters/filters'
      responses:
        '200':
          description: A paginated list of counties
        '500':
          description: Internal server error
  /api/cities:
    get:
      summary: Get a list of U.S. cities
      description: >-
        Returns a list of cities (Places) with optional filters, sorting, field
        selection, and pagination.
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/sortBy'
        - $ref: '#/components/parameters/fields'
        - $ref: '#/components/parameters/includeGeometry'
        - $ref: '#/components/parameters/filters'
      responses:
        '200':
          description: A paginated list of cities
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '429':
          description: Too Many Requests
        '500':
          description: Internal server error
        '504':
          description: Gateway Timeout
  /api/zipcodes:
    get:
      summary: Get a list of U.S. ZIP codes
      description: >-
        Returns a list of ZIP codes with optional filters, sorting, field
        selection, and pagination.
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/sortBy'
        - $ref: '#/components/parameters/fields'
        - $ref: '#/components/parameters/includeGeometry'
        - $ref: '#/components/parameters/filters'
      responses:
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '429':
          description: Too Many Requests
        '500':
          description: Internal server error
        '504':
          description: Gateway Timeout