openapi: 3.0.3
info:
  title: Offenders.io API
  description: >-
    Industry-leading database of National Registered Sex Offenders for the United
    States. Supports criteria-based search by name, date of birth, city, zip, state,
    and geospatial radius queries. Returns rich JSON records including identity,
    photo, address, GPS coordinates, crimes, and risk level.
  version: 1.0.0
  contact:
    name: Offenders.io
    url: https://offenders.io/
servers:
  - url: https://api.offenders.io
    description: Production
paths:
  /sexoffender:
    get:
      summary: Search sex offender registry
      description: >-
        Search the national sex offender registry by name, location, or coordinates.
        Returns matching offender records with identity, address, crimes, and risk
        level information.
      operationId: searchSexOffenders
      tags:
        - Search
      parameters:
        - name: firstName
          in: query
          description: Offender first name (structured search).
          required: false
          schema:
            type: string
        - name: lastName
          in: query
          description: Offender last name (structured search).
          required: false
          schema:
            type: string
        - name: zipcode
          in: query
          description: ZIP code for location-based filtering.
          required: false
          schema:
            type: string
        - name: lat
          in: query
          description: Latitude for geospatial search.
          required: false
          schema:
            type: number
            format: double
        - name: lng
          in: query
          description: Longitude for geospatial search.
          required: false
          schema:
            type: number
            format: double
        - name: radius
          in: query
          description: Search radius in miles (used with lat/lng).
          required: false
          schema:
            type: number
            format: double
        - name: fuzzy
          in: query
          description: Enable typo-tolerant fuzzy matching.
          required: false
          schema:
            type: boolean
            default: false
        - name: key
          in: query
          description: API key for authentication.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Matching offender records.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Offender'
        '401':
          description: Missing or invalid API key.
        '400':
          description: Invalid query parameters.
components:
  schemas:
    Offender:
      type: object
      properties:
        id:
          type: string
          description: Unique offender identifier.
        firstName:
          type: string
        lastName:
          type: string
        photo:
          type: string
          format: uri
          description: URL to offender photo.
        address:
          type: string
        city:
          type: string
        state:
          type: string
        zipcode:
          type: string
        lat:
          type: number
          format: double
        lng:
          type: number
          format: double
        riskLevel:
          type: string
          description: Assigned risk level (e.g., low, medium, high).
        stateData:
          type: object
          description: State-specific record details.
          properties:
            offenses:
              type: array
              items:
                type: object
                properties:
                  description:
                    type: string
                  convictionDate:
                    type: string
                    format: date
                  statuteCode:
                    type: string
                  victimAge:
                    type: integer
  securitySchemes:
    ApiKeyQuery:
      type: apiKey
      in: query
      name: key
security:
  - ApiKeyQuery: []