crimescore-io Incidents API

openapi: 3.2.0
info:
  title: Crimescore Io Incidents API
  version: '1.0'
  contact:
    name: CrimeScore Support
    url: https://crimescore.io
  license:
    name: Proprietary
  description: 'Operations tagged Incidents across 2 of this provider''s published API definitions: crimescore-io.yaml, crimescore-io-openapi.yaml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.crimescore.io/v1
  description: Production
- url: https://api.dev.crimescore.io/v1
  description: Development
security:
- ApiKeyAuth: []
tags:
- name: Incidents
paths:
  /incidents/nearby:
    get:
      operationId: getNearbyIncidents
      summary: Get nearby recent incidents for a location
      description: 'Returns sanitized, normalized recent incidents within a city-scale radius

        around the provided coordinates. Results are limited to a rolling

        24-hour window and do not include raw source payloads, media, user data,

        livestream details, update text, or internal source identifiers. This is

        a nearby incident context endpoint, not a bulk export API. Available on

        Pro and Enterprise, or eligible evaluation access that includes nearby

        incidents. Successful responses consume the current request allowance.'
      parameters:
      - name: lat
        in: query
        required: true
        description: Center latitude (-90 to 90)
        schema:
          type: number
          format: float
          minimum: -90
          maximum: 90
        example: 40.7128
      - name: lng
        in: query
        required: true
        description: Center longitude (-180 to 180)
        schema:
          type: number
          format: float
          minimum: -180
          maximum: 180
        example: -74.006
      - name: radius_m
        in: query
        required: false
        description: Search radius in meters. Capped to city-scale local queries.
        schema:
          type: integer
          default: 5000
          minimum: 100
          maximum: 16000
        example: 5000
      - name: hours
        in: query
        required: false
        description: Rolling lookback window in hours. Currently capped at 24.
        schema:
          type: integer
          default: 24
          minimum: 1
          maximum: 24
        example: 24
      - name: limit
        in: query
        required: false
        description: Maximum number of incidents to return. Pagination is not available in v1.
        schema:
          type: integer
          default: 25
          minimum: 1
          maximum: 100
        example: 25
      responses:
        '200':
          description: Recent incidents found near the requested location
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NearbyIncidentsResponse'
              example:
                capturedAt: '2026-05-07T16:00:00.000Z'
                center:
                  lat: 40.7128
                  lng: -74.006
                radius_m: 5000
                hours: 24
                limit: 25
                count: 2
                scannedCells: 4
                incidents:
                - id: crimescore_9f3a2b7c1d4e5f60718293ab
                  label: Fire activity - NYC area
                  categories:
                  - fire
                  latitude: 40.718
                  longitude: -73.996
                  cityCode: nyc
                  reportedAt: '2026-05-07T15:42:00.000Z'
                  severity: 3
                  level: 2
                  rank: 1
                  distance_m: 1284
                - id: crimescore_4c8d1e2f3a5b60718293abcd
                  label: Traffic incident - NYC area
                  categories:
                  - traffic
                  latitude: 40.689
                  longitude: -74.014
                  cityCode: nyc
                  reportedAt: '2026-05-07T15:25:00.000Z'
                  severity: 1
                  level: 1
                  rank: 2
                  distance_m: 2760
        '400':
          description: Invalid parameters or search radius too broad
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid:
                  summary: Invalid coordinates
                  value:
                    error: INVALID_PARAMETERS
                    message: lat and lng are required
                radius_too_large:
                  summary: Query would scan too many geohash cells
                  value:
                    error: RADIUS_TOO_LARGE
                    message: radius_m is too large for this query
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Key type, capability, or current request allowance does not permit this request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                secret_key_required:
                  summary: Publishable keys cannot call REST API endpoints
                  value:
                    error: SECRET_KEY_REQUIRED
                    message: Use a secret API key for REST API requests. Publishable keys are only for map embeds.
                capability_not_included:
                  summary: Current evaluation access does not include this capability
                  value:
                    error: CAPABILITY_NOT_INCLUDED
                    message: Nearby Incidents is not included with current free access. Upgrade to use this capability.
                quota_exceeded:
                  summary: Current request allowance exhausted
                  value:
                    error: QUOTA_EXCEEDED
                    message: Request quota exceeded
                plan_required:
                  summary: Pro or Enterprise tier required outside eligible evaluation access
                  value:
                    error: FORBIDDEN
                    message: Recent incident endpoints are available on Pro and Enterprise tiers
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: INTERNAL_ERROR
                message: Internal server error
      tags:
      - Incidents
    servers:
    - url: https://api.crimescore.io/v1
      description: Production
    - url: https://api.dev.crimescore.io/v1
      description: Development
components:
  responses:
    Unauthorized:
      description: Missing or invalid API key, suspended organization, or no current organization access. Publishable keys can also return 401 when their tier or domain restrictions fail before the REST secret-key check. A valid key alone does not guarantee access.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: UNAUTHORIZED
            message: Invalid or missing API key
    RateLimited:
      description: Too many requests in a short period. Retry with backoff; this is separate from the organization's request allowance.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: RATE_LIMITED
            message: Too many requests. Please retry after a short delay.
  schemas:
    ErrorResponse:
      type: object
      required:
      - error
      - message
      properties:
        error:
          type: string
          description: Machine-readable error code
        message:
          type: string
          description: Human-readable error description; wording may vary. Use the HTTP status and error code for programmatic handling.
        geoid:
          type: string
          description: Block group ID (present in some error responses)
    NearbyIncidentsResponse:
      type: object
      required:
      - capturedAt
      - center
      - radius_m
      - hours
      - limit
      - count
      - scannedCells
      - incidents
      properties:
        capturedAt:
          type: string
          format: date-time
          description: Time this API response was generated
        center:
          type: object
          required:
          - lat
          - lng
          properties:
            lat:
              type: number
              format: float
            lng:
              type: number
              format: float
        radius_m:
          type: integer
          description: Exact radius used for final distance filtering
        hours:
          type: integer
          description: Rolling recent-activity window
        limit:
          type: integer
          description: Maximum incidents requested
        count:
          type: integer
          description: Number of returned incidents
        scannedCells:
          type: integer
          description: Number of broad geohash cells queried before exact filtering
        incidents:
          type: array
          items:
            $ref: '#/components/schemas/RecentIncident'
    RecentIncident:
      type: object
      required:
      - id
      - label
      - latitude
      - longitude
      - reportedAt
      - distance_m
      properties:
        id:
          type: string
          description: Stable normalized incident identifier
        label:
          type: string
          description: Sanitized, generic incident label
        categories:
          type: array
          items:
            type: string
          description: Normalized incident categories
        latitude:
          type: number
          format: float
        longitude:
          type: number
          format: float
        cityCode:
          type: string
          description: Source market or city code when available
        reportedAt:
          type: string
          format: date-time
        severity:
          type: integer
          nullable: true
        level:
          type: integer
          nullable: true
        rank:
          type: integer
          nullable: true
        distance_m:
          type: integer
          description: Distance from the requested center point in meters
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: Your CrimeScore API key (`cs_secret_*` for server-side, `cs_pub_*` for embeds)
x-refined-from:
- crimescore-io.yaml
- crimescore-io-openapi.yaml