Offenders.io Search API

openapi: 3.0.3
info:
  title: Offenders.io Search 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
security:
- ApiKeyQuery: []
tags:
- name: Search
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