api-docs.yaml

openapi: 3.0.3
info:
  title: Geocoding API
  description: |
    A fast and comprehensive REST API for US ZIP code geocoding, Ohio address lookup, and county boundary data.
    
    ## 🔐 Authentication Required
    
    Most endpoints require an API key. To get started:
    
    1. **Register**: Visit the web interface and create an account
    2. **Get API Key**: Create an API key in your dashboard
    3. **Authenticate**: Use either authentication method:
       - `Authorization: Bearer your-api-key` header, OR
       - `X-API-Key: your-api-key` header
    4. **Test**: Use the "Authorize" button below to set your API key for all requests
    
    ## ✨ Features
    - **Lightning Fast**: PostgreSQL + PostGIS backed with optimized spatial indexes
    - **Multi-Level Coverage**: ZIP codes, cities, addresses, and county boundaries
    - **Comprehensive Data**: Population, density, coordinates, and geographic boundaries
    - **Flexible Search**: Multiple search modes with proximity and filtering
    - **ZIP Code Fallback**: City-based ZIP code lookup for flexible address searching
    - **Rich Metadata**: Timezone, county weights, administrative data
    - **GeoJSON Support**: Ready-to-use geographic data for mapping applications
    - **Usage Tracking**: Monitor your API usage and billing
    
    ## 📊 Data Coverage
    
    ### **🏙️ City Data**
    - **31,000+ US Cities**: Nationwide city coverage with demographics
    - **ZIP Code Associations**: All ZIP codes for each city
    - **Population & Density**: Demographic statistics
    - **Coordinates**: Precise latitude/longitude for each city
    - **Fallback Search**: Find addresses when ZIP code is unknown or incorrect
    
    ### **🏠 Address-Level Data**
    - **5.5+ Million Ohio Addresses**: Complete street-level geocoding
    - **Precise Coordinates**: PostGIS geometry with spatial indexing
    - **Administrative Data**: City, county, ZIP code associations
    
    ### **📮 ZIP Code Data**  
    - **33,000+ US ZIP Codes**: Comprehensive national coverage
    - **Geographic Coordinates**: Latitude/longitude with precision indicators
    - **Demographics**: Population and density statistics
    - **Administrative**: County associations and timezone data
    
    ### **🗺️ County Boundaries**
    - **89 Ohio Counties**: Complete polygon boundary data
    - **GeoJSON Format**: Ready for Leaflet, Mapbox, OpenLayers
    - **Spatial Queries**: Bounding box intersections and proximity searches
    - **Statistics**: Address counts and administrative metadata
    
  version: 1.0.0
  contact:
    name: API Support
    url: https://github.com/keonik/geocoding-api
    email: john.k.fay@gmail.com
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: http://localhost:8080/api/v1
    description: Development server
  - url: https://geocode.jfay.dev/api/v1
    description: Production server

paths:
  /health:
    get:
      summary: Health Check
      description: Returns the current health status of the API service
      operationId: healthCheck
      tags:
        - System
      responses:
        '200':
          description: Service is healthy
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: "healthy"
                  service:
                    type: string
                    example: "geocoding-api"
                  version:
                    type: string
                    example: "1.0.0"

  /geocode/{zipcode}:
    get:
      summary: Get ZIP Code Details
      description: |
        Retrieve comprehensive geographic and demographic information for a specific US ZIP code.
        
        Returns detailed location data including coordinates, population statistics, 
        administrative boundaries, and timezone information.
        
        **Authentication Required**: This endpoint requires a valid API key using either `X-API-Key` header or `Authorization: Bearer` format.
      operationId: getZipCode
      security:
        - ApiKeyAuth: []
      tags:
        - Geocoding
      parameters:
        - name: zipcode
          in: path
          required: true
          description: US ZIP code (5 or 9 digits)
          schema:
            type: string
            pattern: '^\d{5}(-\d{4})?$'
            example: "10001"
      responses:
        '200':
          description: ZIP code found successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeocodeResponse'
              examples:
                manhattan_zip:
                  summary: Manhattan ZIP code example
                  value:
                    success: true
                    data:
                      zip_code: "10001"
                      city_name: "New York"
                      state_code: "NY"
                      state_name: "New York"
                      zcta: true
                      population: 21102.0
                      density: 35400.5
                      primary_county_code: "36061"
                      primary_county_name: "New York"
                      county_weights:
                        "36061": "100"
                      county_names: ["New York"]
                      county_codes: ["36061"]
                      imprecise: false
                      military: false
                      timezone: "America/New_York"
                      latitude: 40.75066
                      longitude: -73.99670
                    count: 1
        '400':
          description: Invalid ZIP code format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error: "Invalid ZIP code format"
        '404':
          description: ZIP code not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error: "ZIP code not found"
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /search:
    get:
      summary: Search ZIP Codes by City
      description: |
        Search for ZIP codes by city name with optional state filtering.
        
        Supports partial city name matching and returns multiple results.
        Useful for autocomplete functionality or when exact ZIP code is unknown.
      operationId: searchZipCodes
      security:
        - ApiKeyAuth: []
      tags:
        - Search
      parameters:
        - name: city
          in: query
          required: true
          description: City name or partial city name to search for
          schema:
            type: string
            minLength: 2
            example: "Springfield"
        - name: state
          in: query
          required: false
          description: Two-letter state code to filter results
          schema:
            type: string
            pattern: '^[A-Z]{2}$'
            example: "IL"
        - name: limit
          in: query
          required: false
          description: Maximum number of results to return
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50
            example: 25
      responses:
        '200':
          description: Search completed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
              examples:
                springfield_search:
                  summary: Springfield search results
                  value:
                    success: true
                    data:
                      - zip_code: "62701"
                        city_name: "Springfield"
                        state_code: "IL"
                        state_name: "Illinois"
                        latitude: 39.78172
                        longitude: -89.64371
                      - zip_code: "62702"
                        city_name: "Springfield"
                        state_code: "IL"
                        state_name: "Illinois"
                        latitude: 39.76009
                        longitude: -89.60733
                    count: 2
        '400':
          description: Invalid search parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /distance/{from}/{to}:
    get:
      summary: Calculate Distance Between ZIP Codes
      description: |
        Calculate the precise distance between two ZIP codes using the Haversine formula.
        
        Returns distance in both miles and kilometers for accurate geographic calculations.
        Perfect for logistics, delivery radius validation, and distance-based searches.
      operationId: calculateDistance
      security:
        - ApiKeyAuth: []
      tags:
        - Distance
      parameters:
        - name: from
          in: path
          required: true
          description: Starting ZIP code
          schema:
            type: string
            pattern: '^\d{5}(-\d{4})?$'
            example: "10001"
        - name: to
          in: path
          required: true
          description: Destination ZIP code
          schema:
            type: string
            pattern: '^\d{5}(-\d{4})?$'
            example: "90210"
      responses:
        '200':
          description: Distance calculated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DistanceResponse'
              example:
                success: true
                data:
                  from_zip_code: "10001"
                  to_zip_code: "90210"
                  distance_miles: 2445.5
                  distance_km: 3936.2
                count: 1
        '400':
          description: Invalid ZIP code format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /nearby/{zipcode}:
    get:
      summary: Find Nearby ZIP Codes
      description: |
        Find all ZIP codes within a specified radius of a center ZIP code.
        
        Returns ZIP codes sorted by distance with complete location data.
        Ideal for location-based services, delivery zones, and proximity marketing.
      operationId: findNearbyZipCodes
      security:
        - ApiKeyAuth: []
      tags:
        - Distance
      parameters:
        - name: zipcode
          in: path
          required: true
          description: Center ZIP code to search around
          schema:
            type: string
            pattern: '^\d{5}(-\d{4})?$'
            example: "10001"
        - name: radius
          in: query
          required: false
          description: Search radius in miles
          schema:
            type: number
            format: double
            minimum: 0.1
            maximum: 100
            default: 1
            example: 5
        - name: limit
          in: query
          required: false
          description: Maximum number of results to return
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 50
            example: 25
      responses:
        '200':
          description: Nearby ZIP codes found successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NearbyResponse'
              examples:
                nearby_results:
                  summary: ZIP codes within 5 miles of Manhattan
                  value:
                    success: true
                    data:
                      - zip_code:
                          zip_code: "10002"
                          city_name: "New York"
                          state_code: "NY"
                          latitude: 40.71571
                          longitude: -73.98803
                        distance_miles: 0.8
                        distance_km: 1.3
                      - zip_code:
                          zip_code: "10003"
                          city_name: "New York"
                          state_code: "NY"
                          latitude: 40.73168
                          longitude: -73.98975
                        distance_miles: 1.2
                        distance_km: 1.9
                    count: 2
        '400':
          description: Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /proximity/{center}/{target}:
    get:
      summary: Check ZIP Code Proximity
      description: |
        Check if a target ZIP code is within a specified radius of a center ZIP code.
        
        Returns boolean result with actual distance for precise proximity checking.
        Useful for validation, filtering, and business rule enforcement.
      operationId: checkZipCodeProximity
      security:
        - ApiKeyAuth: []
      tags:
        - Distance
      parameters:
        - name: center
          in: path
          required: true
          description: Center ZIP code for proximity check
          schema:
            type: string
            pattern: '^\d{5}(-\d{4})?$'
            example: "10001"
        - name: target
          in: path
          required: true
          description: Target ZIP code to check proximity for
          schema:
            type: string
            pattern: '^\d{5}(-\d{4})?$'
            example: "10002"
        - name: radius
          in: query
          required: false
          description: Radius in miles for proximity check
          schema:
            type: number
            format: double
            minimum: 0.1
            maximum: 100
            default: 1
            example: 1
      responses:
        '200':
          description: Proximity check completed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProximityResponse'
              example:
                success: true
                data:
                  center_zip_code: "10001"
                  target_zip_code: "10002"
                  radius_miles: 1
                  is_within_radius: true
                  actual_distance_miles: 0.5
                  actual_distance_km: 0.8
                count: 1
        '400':
          description: Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /addresses:
    get:
      summary: Search Ohio Addresses
      description: |
        Search for addresses within Ohio with flexible filtering and intelligent full-text search.
        
        **Enhanced Full-Text Search**: The `query` parameter now searches the complete formatted address,
        making it easier to find addresses with partial information in any order:
        - `query=123 main columbus` → Finds "123 Main St, Columbus, OH 43215"
        - `query=main st 43215` → Finds Main Street addresses in ZIP 43215
        - `query=franklin county main` → Finds Main Street in Franklin County
        
        The search uses relevance scoring with the formatted full address getting highest priority,
        followed by individual fields (street, house number, city, ZIP code, county).
        
        **Features:**
        - Flexible text search across all address components
        - Specific field filtering (city, county, ZIP code)
        - Proximity search by coordinates and radius
        - Relevance-based result ranking
        - Pagination support
        
        Perfect for address validation, autocomplete, and location-based services.
      operationId: searchOhioAddresses
      security:
        - ApiKeyAuth: []
      tags:
        - Ohio Addresses
      parameters:
        - name: query
          in: query
          required: false
          description: General search query (searches across address fields)
          schema:
            type: string
            example: "123 Main St"
        - name: house_number
          in: query
          required: false
          description: House number to search for
          schema:
            type: string
            example: "123"
        - name: street
          in: query
          required: false
          description: Street name to search for
          schema:
            type: string
            example: "Main St"
        - name: city
          in: query
          required: false
          description: City name to filter by
          schema:
            type: string
            example: "Columbus"
        - name: county
          in: query
          required: false
          description: County name to filter by
          schema:
            type: string
            example: "Franklin"
        - name: postcode
          in: query
          required: false
          description: ZIP code to filter by
          schema:
            type: string
            example: "43215"
        - name: lat
          in: query
          required: false
          description: Latitude for proximity search (requires lon and radius)
          schema:
            type: number
            format: double
            example: 39.9612
        - name: lon
          in: query
          required: false
          description: Longitude for proximity search (requires lat and radius)
          schema:
            type: number
            format: double
            example: -82.9988
        - name: radius
          in: query
          required: false
          description: Search radius in miles for proximity search
          schema:
            type: number
            format: double
            minimum: 0.1
            maximum: 50
            default: 1
            example: 5
        - name: limit
          in: query
          required: false
          description: Maximum number of results to return
          schema:
            type: integer
            minimum: 1
            maximum: 1000
            default: 100
            example: 50
        - name: offset
          in: query
          required: false
          description: Number of results to skip for pagination
          schema:
            type: integer
            minimum: 0
            default: 0
            example: 0
        - name: sort
          in: query
          required: false
          description: Sort order for results
          schema:
            type: string
            enum: [distance, address, city, county]
            default: address
            example: distance
      responses:
        '200':
          description: Address search completed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddressSearchResponse'
        '400':
          description: Invalid search parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /addresses/search:
    get:
      summary: Full-Text Address Search
      description: |
        Fast full-text search across complete formatted addresses using the indexed `full_address` column.
        
        **Simple and Fast**: Just search the complete address string as you'd type it:
        - `q=7 westerfield drive` → Finds "7 Westerfield Dr, City, OH 12345"
        - `q=123 main st columbus` → Finds Main Street addresses in Columbus
        - `q=maple street 43215` → Finds Maple Street in ZIP 43215
        
        This endpoint uses PostgreSQL's trigram indexes for blazing-fast partial matches
        on the full formatted address. Perfect for autocomplete and quick address lookups.
        
        **Use this when:**
        - You want simple, Google-like address search
        - You need fast autocomplete suggestions
        - You have a partial or complete address string
        
        **Use `/addresses` when:**
        - You need to filter by specific fields (county, city, ZIP)
        - You want proximity/radius search
        - You need pagination for large result sets
      operationId: fullTextSearchAddresses
      security:
        - ApiKeyAuth: []
      tags:
        - Ohio Addresses
      parameters:
        - name: q
          in: query
          required: true
          description: Address search query (partial or complete address)
          schema:
            type: string
            minLength: 2
            example: "7 westerfield drive"
        - name: limit
          in: query
          required: false
          description: Maximum number of results to return (1-500)
          schema:
            type: integer
            minimum: 1
            maximum: 500
            default: 50
            example: 10
      responses:
        '200':
          description: Search completed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/OhioAddress'
                  count:
                    type: integer
                    description: Number of addresses returned
                    example: 5
                  query:
                    type: string
                    description: The search query that was executed
                    example: "7 westerfield drive"
              example:
                success: true
                data:
                  - id: 12345
                    house_number: "7"
                    street: "Westerfield Dr"
                    city: "Columbus"
                    county: "Franklin"
                    postcode: "43215"
                    full_address: "7 Westerfield Dr, Columbus, OH 43215"
                    latitude: 39.9612
                    longitude: -82.9988
                count: 1
                query: "7 westerfield drive"
        '400':
          description: Invalid search parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /addresses/{id}:
    get:
      summary: Get Address Details
      description: |
        Retrieve detailed information for a specific Ohio address by its unique ID.
        
        Returns complete address information including coordinates and administrative data.
      operationId: getOhioAddress
      security:
        - ApiKeyAuth: []
      tags:
        - Ohio Addresses
      parameters:
        - name: id
          in: path
          required: true
          description: Unique address ID
          schema:
            type: integer
            example: 12345
      responses:
        '200':
          description: Address found successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddressResponse'
        '404':
          description: Address not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /counties:
    get:
      summary: List Ohio Counties
      description: |
        Retrieve a list of all Ohio counties with basic information and address counts.
        
        Supports filtering by name, address count ranges, and pagination.
        Perfect for building county selectors and administrative dashboards.
      operationId: getCounties
      security:
        - ApiKeyAuth: []
      tags:
        - County Boundaries
      parameters:
        - name: name
          in: query
          required: false
          description: Filter counties by name (partial match)
          schema:
            type: string
            example: "Franklin"
        - name: min_addresses
          in: query
          required: false
          description: Minimum number of addresses per county
          schema:
            type: integer
            minimum: 0
            example: 10000
        - name: max_addresses
          in: query
          required: false
          description: Maximum number of addresses per county
          schema:
            type: integer
            minimum: 0
            example: 500000
        - name: limit
          in: query
          required: false
          description: Maximum number of results to return
          schema:
            type: integer
            minimum: 1
            maximum: 1000
            default: 100
            example: 25
        - name: offset
          in: query
          required: false
          description: Number of results to skip for pagination
          schema:
            type: integer
            minimum: 0
            default: 0
            example: 0
      responses:
        '200':
          description: Counties retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CountyListResponse'
        '400':
          description: Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /counties/{name}:
    get:
      summary: Get County Details
      description: |
        Retrieve detailed information about a specific Ohio county.
        
        Returns county metadata, statistics, and administrative information.
      operationId: getCountyDetail
      security:
        - ApiKeyAuth: []
      tags:
        - County Boundaries
      parameters:
        - name: name
          in: path
          required: true
          description: County name (case-insensitive)
          schema:
            type: string
            example: "Franklin"
      responses:
        '200':
          description: County found successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CountyResponse'
        '404':
          description: County not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /counties/{name}/boundary:
    get:
      summary: Get County Boundary
      description: |
        Retrieve the geographic boundary polygon for a specific Ohio county in GeoJSON format.
        
        Returns GeoJSON FeatureCollection ready for use with mapping libraries like Leaflet, Mapbox, or OpenLayers.
        Perfect for visualizing county boundaries on interactive maps.
      operationId: getCountyBoundary
      security:
        - ApiKeyAuth: []
      tags:
        - County Boundaries
      parameters:
        - name: name
          in: path
          required: true
          description: County name (case-insensitive)
          schema:
            type: string
            example: "Franklin"
      responses:
        '200':
          description: County boundary retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeoJSONFeatureCollection'
              example:
                type: "FeatureCollection"
                features:
                  - type: "Feature"
                    properties:
                      county_name: "Franklin"
                      source_name: "franklin-addresses-county"
                      layer: "addresses"
                      address_count: 852417
                      stats: {}
                    geometry:
                      type: "Polygon"
                      coordinates: [[]]
        '404':
          description: County not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /counties/bounds/search:
    get:
      summary: Find Counties in Bounding Box
      description: |
        Find all Ohio counties that intersect with a specified geographic bounding box.
        
        Returns counties sorted by address count. Useful for map-based applications
        where you need to know which counties are visible in the current viewport.
      operationId: getCountiesInBounds
      security:
        - ApiKeyAuth: []
      tags:
        - County Boundaries
      parameters:
        - name: min_lat
          in: query
          required: true
          description: Minimum latitude of bounding box
          schema:
            type: number
            format: double
            example: 39.5
        - name: min_lon
          in: query
          required: true
          description: Minimum longitude of bounding box
          schema:
            type: number
            format: double
            example: -84.5
        - name: max_lat
          in: query
          required: true
          description: Maximum latitude of bounding box
          schema:
            type: number
            format: double
            example: 40.5
        - name: max_lon
          in: query
          required: true
          description: Maximum longitude of bounding box
          schema:
            type: number
            format: double
            example: -82.5
      responses:
        '200':
          description: Counties in bounds retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CountyBoundsResponse'
        '400':
          description: Invalid bounding box parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /cities:
    get:
      summary: Search US Cities
      description: |
        Search for US cities using various filters including name, state, county, population, and location-based queries.
        
        The endpoint supports fuzzy text matching on city names and can filter by:
        - City name (partial match)
        - State (by ID or name)
        - County name
        - Minimum population
        - Geographic proximity (latitude/longitude with radius)
        
        Results are ordered by ranking (major cities first) and population.
        
        **Use Case**: Use this endpoint as a fallback when ZIP code searches fail. For example,
        if searching for an address with an incorrect ZIP code, search for the city to get all
        valid ZIP codes for that city, then search addresses in each ZIP.
      operationId: searchCities
      security:
        - ApiKeyAuth: []
      tags:
        - Cities
      parameters:
        - name: query
          in: query
          required: false
          description: Free text search query for city name
          schema:
            type: string
            example: "Dayton"
        - name: city
          in: query
          required: false
          description: Filter by city name (supports fuzzy matching)
          schema:
            type: string
            example: "Dayton"
        - name: state
          in: query
          required: false
          description: Filter by state ID (e.g., "OH") or state name (e.g., "Ohio")
          schema:
            type: string
            example: "OH"
        - name: county
          in: query
          required: false
          description: Filter by county name
          schema:
            type: string
            example: "Montgomery"
        - name: lat
          in: query
          required: false
          description: Latitude for location-based search (requires lng and optionally radius)
          schema:
            type: number
            format: double
            example: 39.7589
        - name: lng
          in: query
          required: false
          description: Longitude for location-based search (requires lat and optionally radius)
          schema:
            type: number
            format: double
            example: -84.1916
        - name: radius
          in: query
          required: false
          description: Search radius in kilometers (requires lat and lng)
          schema:
            type: number
            format: double
            example: 50
        - name: min_population
          in: query
          required: false
          description: Minimum population filter
          schema:
            type: integer
            example: 100000
        - name: limit
          in: query
          required: false
          description: Maximum number of results to return (max 100)
          schema:
            type: integer
            default: 10
            maximum: 100
            example: 10
        - name: offset
          in: query
          required: false
          description: Number of results to skip for pagination
          schema:
            type: integer
            default: 0
            example: 0
      responses:
        '200':
          description: Cities found successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CitySearchResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /cities/{id}:
    get:
      summary: Get City by ID
      description: |
        Retrieve detailed information for a specific city by its unique ID.
        
        Returns comprehensive city data including coordinates, population, associated ZIP codes,
        and administrative information.
      operationId: getCityById
      security:
        - ApiKeyAuth: []
      tags:
        - Cities
      parameters:
        - name: id
          in: path
          required: true
          description: Unique city identifier
          schema:
            type: integer
            format: int64
            example: 12345
      responses:
        '200':
          description: City found successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CityResponse'
        '400':
          description: Invalid city ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: City not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /cities/zips:
    get:
      summary: Get ZIP Codes for a City
      description: |
        Retrieve all ZIP codes associated with a specific city.
        
        **Important Use Case**: This endpoint is essential for the ZIP code fallback pattern.
        When searching for an address with an incorrect or unknown ZIP code:
        1. Use this endpoint to get all valid ZIP codes for the city
        2. Search addresses in each returned ZIP code
        3. Find the correct address match
        
        Example: Looking for "1424 WYOMING STREET, DAYTON, OH" but unsure of ZIP code.
        Query this endpoint with `city=Dayton&state=OH` to get all Dayton ZIP codes
        (45401, 45402, 45410, etc.), then search addresses in each.
      operationId: getCityZipCodes
      security:
        - ApiKeyAuth: []
      tags:
        - Cities
      parameters:
        - name: city
          in: query
          required: true
          description: City name
          schema:
            type: string
            example: "Dayton"
        - name: state
          in: query
          required: true
          description: State ID (e.g., "OH") or full state name (e.g., "Ohio")
          schema:
            type: string
            example: "OH"
      responses:
        '200':
          description: ZIP codes retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CityZipsResponse'
        '400':
          description: Missing required parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /admin/load-data:
    post:
      summary: Load ZIP Code Data
      description: |
        **Admin endpoint** to load ZIP code data from CSV file into the database.
        
        ⚠️ **Note**: This endpoint should be protected with authentication in production environments.
        
        The endpoint will:
        1. Parse the CSV file
        2. Insert/update records in the database
        3. Handle duplicate ZIP codes via upsert operations
      operationId: loadData
      tags:
        - Admin
      parameters:
        - name: file
          in: query
          required: false
          description: Path to CSV file (defaults to standard location)
          schema:
            type: string
            example: "georef-united-states-of-america-zc-point.csv"
      responses:
        '200':
          description: Data loaded successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
              example:
                success: true
                data: "CSV data loaded successfully"
        '500':
          description: Failed to load data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /admin/counties:
    get:
      summary: Get County Statistics
      description: |
        **Admin endpoint** to retrieve comprehensive statistics about Ohio counties.
        
        Returns aggregated data including total counties, address counts, and distribution metrics.
      operationId: getCountyStats
      tags:
        - Admin
      responses:
        '200':
          description: County statistics retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CountyStatsResponse'
        '500':
          description: Failed to retrieve statistics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: |
        API key authentication. Supports two methods:
        
        **Method 1 - X-API-Key Header (Recommended):**
        ```
        X-API-Key: your-api-key-here
        ```
        
        **Method 2 - Authorization Bearer:**
        ```
        Authorization: Bearer your-api-key-here
        ```
        
        Get your API key by:
        1. Register/login at the web interface
        2. Create an API key in your dashboard
        3. Use either authentication method above
  
  schemas:
    ZipCode:
      type: object
      description: Complete ZIP code information including geographic and demographic data
      properties:
        zip_code:
          type: string
          description: The ZIP code identifier
          example: "10001"
        city_name:
          type: string
          description: Official USPS city name
          example: "New York"
        state_code:
          type: string
          description: Two-letter state abbreviation
          example: "NY"
        state_name:
          type: string
          description: Full state name
          example: "New York"
        zcta:
          type: boolean
          description: Whether this is a ZIP Code Tabulation Area
          example: true
        zcta_parent:
          type: string
          nullable: true
          description: Parent ZCTA if applicable
          example: null
        population:
          type: number
          nullable: true
          description: Population count for this ZIP code area
          example: 21102.0
        density:
          type: number
          nullable: true
          description: Population density per square mile
          example: 35400.5
        primary_county_code:
          type: string
          description: FIPS code of the primary county
          example: "36061"
        primary_county_name:
          type: string
          description: Name of the primary county
          example: "New York"
        county_weights:
          type: object
          description: JSON object with county codes and their percentage weights
          additionalProperties:
            type: string
          example:
            "36061": "100"
        county_names:
          type: array
          items:
            type: string
          description: Array of all county names for this ZIP code
          example: ["New York"]
        county_codes:
          type: array
          items:
            type: string
          description: Array of all county FIPS codes for this ZIP code
          example: ["36061"]
        imprecise:
          type: boolean
          description: Whether the coordinates are imprecise
          example: false
        military:
          type: boolean
          description: Whether this is a military ZIP code
          example: false
        timezone:
          type: string
          description: IANA timezone identifier
          example: "America/New_York"
        latitude:
          type: number
          format: double
          description: Latitude coordinate (WGS84)
          example: 40.75066
        longitude:
          type: number
          format: double
          description: Longitude coordinate (WGS84)
          example: -73.99670

    GeocodeResponse:
      type: object
      properties:
        success:
          type: boolean
          description: Whether the request was successful
          example: true
        data:
          $ref: '#/components/schemas/ZipCode'
        count:
          type: integer
          description: Number of results returned
          example: 1

    SearchResponse:
      type: object
      properties:
        success:
          type: boolean
          description: Whether the request was successful
          example: true
        data:
          type: array
          items:
            $ref: '#/components/schemas/ZipCode'
          description: Array of matching ZIP codes
        count:
          type: integer
          description: Number of results returned
          example: 2

    SuccessResponse:
      type: object
      properties:
        success:
          type: boolean
          description: Whether the request was successful
          example: true
        data:
          type: string
          description: Success message
          example: "Operation completed successfully"

    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          description: Whether the request was successful
          example: false
        error:
          type: string
          description: Error message describing what went wrong
          example: "ZIP code not found"

    DistanceResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          type: object
          properties:
            from_zip_code:
              type: string
              description: Starting ZIP code
              example: "10001"
            to_zip_code:
              type: string
              description: Destination ZIP code
              example: "90210"
            distance_miles:
              type: number
              format: double
              description: Distance in miles
              example: 2445.5
            distance_km:
              type: number
              format: double
              description: Distance in kilometers
              example: 3936.2
        count:
          type: integer
          example: 1

    NearbyZipCode:
      type: object
      properties:
        zip_code:
          $ref: '#/components/schemas/ZipCode'
        distance_miles:
          type: number
          format: double
          description: Distance from center point in miles
          example: 0.8
        distance_km:
          type: number
          format: double
          description: Distance from center point in kilometers
          example: 1.3

    NearbyResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          type: array
          items:
            $ref: '#/components/schemas/NearbyZipCode'
        count:
          type: integer
          description: Number of ZIP codes found within radius
          example: 15

    ProximityResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          type: object
          properties:
            center_zip_code:
              type: string
              description: Center ZIP code for proximity check
              example: "10001"
            target_zip_code:
              type: string
              description: Target ZIP code being checked
              example: "10002"
            radius_miles:
              type: number
              format: double
              description: Specified radius in miles
              example: 1
            is_within_radius:
              type: boolean
              description: Whether target is within the specified radius
              example: true
            actual_distance_miles:
              type: number
              format: double
              description: Actual distance between ZIP codes in miles
              example: 0.5
            actual_distance_km:
              type: number
              format: double
              description: Actual distance between ZIP codes in kilometers
              example: 0.8
        count:
          type: integer
          example: 1

    OhioAddress:
      type: object
      description: Complete Ohio address information with geographic coordinates
      properties:
        id:
          type: integer
          description: Unique address identifier
          example: 12345
        hash:
          type: string
          description: Unique hash for the address
          example: "abc123def456"
        house_number:
          type: string
          description: House number
          example: "123"
        street:
          type: string
          description: Street name
          example: "Main St"
        unit:
          type: string
          nullable: true
          description: Unit or apartment number
          example: "Apt 2B"
        city:
          type: string
          description: City name
          example: "Columbus"
        district:
          type: string
          nullable: true
          description: District or neighborhood
          example: "Downtown"
        region:
          type: string
          description: State or region
          example: "Ohio"
        postcode:
          type: string
          description: ZIP code
          example: "43215"
        county:
          type: string
          description: County name
          example: "Franklin"
        full_address:
          type: string
          description: Complete formatted address string
          example: "123 Main St, Columbus, OH 43215"
        latitude:
          type: number
          format: double
          description: Latitude coordinate (WGS84)
          example: 39.9612
        longitude:
          type: number
          format: double
          description: Longitude coordinate (WGS84)
          example: -82.9988

    AddressSearchResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          type: array
          items:
            allOf:
              - $ref: '#/components/schemas/OhioAddress'
              - type: object
                properties:
                  distance_miles:
                    type: number
                    format: double
                    description: Distance in miles (only present for proximity searches)
                    example: 0.5
        count:
          type: integer
          description: Number of addresses returned
          example: 25
        total:
          type: integer
          description: Total number of matching addresses
          example: 150

    AddressResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          $ref: '#/components/schemas/OhioAddress'

    CountyBasic:
      type: object
      description: Basic county information
      properties:
        id:
          type: integer
          description: Unique county identifier
          example: 1
        county_name:
          type: string
          description: County name
          example: "Franklin"
        address_count:
          type: integer
          description: Number of addresses in this county
          example: 852417

    CountyDetailed:
      allOf:
        - $ref: '#/components/schemas/CountyBasic'
        - type: object
          properties:
            source_name:
              type: string
              description: Source dataset name
              example: "franklin-addresses-county"
            layer:
              type: string
              description: Data layer type
              example: "addresses"
            stats:
              type: object
              description: Additional statistics about the county
              additionalProperties: true
              example: {}
            bounds_geometry:
              type: string
              description: County boundary in WKT format
              example: "POLYGON((-83.2 39.8, -82.8 39.8, ...))"
            created_at:
              type: string
              format: date-time
              description: Record creation timestamp
              example: "2025-11-11T00:42:11Z"
            updated_at:
              type: string
              format: date-time
              description: Record last update timestamp
              example: "2025-11-11T00:42:11Z"

    CountyListResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          type: array
          items:
            $ref: '#/components/schemas/CountyBasic'
        count:
          type: integer
          description: Number of counties returned
          example: 25

    CountyResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          $ref: '#/components/schemas/CountyDetailed'

    CountyBoundsResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          type: array
          items:
            $ref: '#/components/schemas/CountyBasic'
        count:
          type: integer
          description: Number of counties in bounds
          example: 5
        bounds:
          type: object
          description: The search bounding box
          properties:
            min_lat:
              type: number
              format: double
              example: 39.5
            min_lon:
              type: number
              format: double
              example: -84.5
            max_lat:
              type: number
              format: double
              example: 40.5
            max_lon:
              type: number
              format: double
              example: -82.5

    CountyStatsResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          type: object
          properties:
            total_counties:
              type: integer
              description: Total number of Ohio counties
              example: 89
            total_addresses:
              type: integer
              description: Total number of addresses across all counties
              example: 5551283
            avg_addresses_per_county:
              type: number
              format: double
              description: Average addresses per county
              example: 62373.6
            max_addresses_per_county:
              type: integer
              description: Maximum addresses in a single county
              example: 852417
            min_addresses_per_county:
              type: integer
              description: Minimum addresses in a single county
              example: 1832

    GeoJSONGeometry:
      type: object
      description: GeoJSON geometry object
      properties:
        type:
          type: string
          enum: [Point, LineString, Polygon, MultiPoint, MultiLineString, MultiPolygon]
          example: "Polygon"
        coordinates:
          type: array
          description: Coordinate array (format depends on geometry type)
          example: [[[-83.2, 39.8], [-82.8, 39.8], [-82.8, 40.2], [-83.2, 40.2], [-83.2, 39.8]]]

    GeoJSONFeature:
      type: object
      description: GeoJSON feature object
      properties:
        type:
          type: string
          enum: [Feature]
          example: "Feature"
        properties:
          type: object
          description: Feature properties
          properties:
            county_name:
              type: string
              example: "Franklin"
            source_name:
              type: string
              example: "franklin-addresses-county"
            layer:
              type: string
              example: "addresses"
            address_count:
              type: integer
              example: 852417
            stats:
              type: object
              additionalProperties: true
              example: {}
        geometry:
          $ref: '#/components/schemas/GeoJSONGeometry'

    GeoJSONFeatureCollection:
      type: object
      description: GeoJSON FeatureCollection
      properties:
        type:
          type: string
          enum: [FeatureCollection]
          example: "FeatureCollection"
        features:
          type: array
          items:
            $ref: '#/components/schemas/GeoJSONFeature'
          description: Array of GeoJSON features

    City:
      type: object
      description: US city information including location, demographics, and associated ZIP codes
      properties:
        id:
          type: integer
          format: int64
          description: Unique city identifier
          example: 12345
        city:
          type: string
          description: City name
          example: "Dayton"
        city_ascii:
          type: string
          description: ASCII-only version of city name
          example: "Dayton"
        state_id:
          type: string
          description: Two-letter state code
          example: "OH"
        state_name:
          type: string
          description: Full state name
          example: "Ohio"
        county_fips:
          type: string
          description: County FIPS code
          example: "39113"
        county_name:
          type: string
          description: County name
          example: "Montgomery"
        lat:
          type: number
          format: double
          description: Latitude coordinate
          example: 39.7589
        lng:
          type: number
          format: double
          description: Longitude coordinate
          example: -84.1916
        population:
          type: integer
          description: City population
          example: 140407
        density:
          type: number
          format: double
          description: Population density (people per sq km)
          example: 1234.56
        source:
          type: string
          description: Data source
          example: "shape"
        military:
          type: boolean
          description: Whether this is a military base
          example: false
        incorporated:
          type: boolean
          description: Whether the city is incorporated
          example: true
        timezone:
          type: string
          description: IANA timezone identifier
          example: "America/New_York"
        ranking:
          type: integer
          description: City ranking (1 = major city)
          example: 1
        zips:
          type: string
          description: Space-separated list of ZIP codes
          example: "45401 45402 45403 45404 45405 45406 45409 45410 45414 45415"
        external_id:
          type: string
          description: External identifier from source data
          example: "1840034016"

    CitySearchResponse:
      type: object
      description: Response for city search operations
      properties:
        success:
          type: boolean
          example: true
        data:
          type: array
          items:
            $ref: '#/components/schemas/City'
        count:
          type: integer
          description: Number of results in current response
          example: 1
        total:
          type: integer
          description: Total number of matching cities
          example: 1
        query:
          type: string
          description: Original search query
          example: "Dayton"
        filters:
          type: object
          description: Applied filters
          additionalProperties: true
          example:
            state: "OH"
        message:
          type: string
          description: Optional message
        error:
          type: string
          description: Error message if success is false

    CityResponse:
      type: object
      description: Response for single city lookup
      properties:
        success:
          type: boolean
          example: true
        data:
          type: array
          items:
            $ref: '#/components/schemas/City'
        count:
          type: integer
          example: 1
        total:
          type: integer
          example: 1

    CityZipsResponse:
      type: object
      description: Response containing ZIP codes for a city
      properties:
        success:
          type: boolean
          example: true
        data:
          type: object
          properties:
            city:
              type: string
              description: City name
              example: "Dayton"
            state:
              type: string
              description: State code
              example: "OH"
            zips:
              type: array
              items:
                type: string
              description: Array of ZIP codes
              example: ["45401", "45402", "45403", "45404", "45405", "45406", "45409", "45410"]
            count:
              type: integer
              description: Number of ZIP codes
              example: 8

tags:
  - name: Geocoding
    description: Core geocoding operations for ZIP code lookup
  - name: Search
    description: Search and discovery operations
  - name: Distance
    description: Distance calculations and proximity operations between ZIP codes
  - name: Ohio Addresses
    description: Ohio address search and lookup operations (5.5M+ addresses)
  - name: County Boundaries
    description: Ohio county boundary and geographic data operations (89 counties)
  - name: Cities
    description: US city search and ZIP code lookup operations (31,000+ cities). Use for fallback when ZIP code is unknown or incorrect.
  - name: Admin
    description: Administrative operations for data management
  - name: System
    description: System health and monitoring endpoints