crimescore-io Geocode API

openapi: 3.2.0
info:
  title: Crimescore Io Geocode API
  version: '1.0'
  contact:
    name: CrimeScore Support
    url: https://crimescore.io
  license:
    name: Proprietary
  description: 'Operations tagged Geocode 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: Geocode
paths:
  /geocode:
    get:
      operationId: geocodeAddress
      summary: Geocode a US address for public map search
      security: []
      description: 'Public helper endpoint used by the CrimeScore map finder. It resolves a

        US address through the Census Geocoder and returns only normalized

        location fields needed to center the public map. It does not return a

        crime score, does not consume quota, and is not a substitute for the

        authenticated score API.'
      parameters:
      - name: address
        in: query
        required: true
        description: US address to resolve. Use a complete street, city, and state when possible.
        schema:
          type: string
          minLength: 1
          maxLength: 180
        example: 1600 Pennsylvania Ave NW, Washington, DC
      responses:
        '200':
          description: Address matched
          content:
            application/json:
              schema:
                type: object
                required:
                - query
                - matched
                - lat
                - lng
                - matchedAddress
                properties:
                  query:
                    type: string
                  matched:
                    type: boolean
                    const: true
                  lat:
                    type: number
                    format: float
                  lng:
                    type: number
                    format: float
                  matchedAddress:
                    type: string
                  state:
                    type: string
                  county_fips:
                    type: string
                  tract:
                    type: string
                  block_group:
                    type: string
                  matches:
                    type: array
                    description: Up to five normalized Census address matches. The first item is also repeated at the top level for simple callers.
                    items:
                      type: object
                      required:
                      - query
                      - matched
                      - lat
                      - lng
                      - matchedAddress
                      properties:
                        query:
                          type: string
                        matched:
                          type: boolean
                        lat:
                          type: number
                          format: float
                        lng:
                          type: number
                          format: float
                        matchedAddress:
                          type: string
                        state:
                          type: string
                        county_fips:
                          type: string
                        tract:
                          type: string
                        block_group:
                          type: string
              example:
                query: 1600 Pennsylvania Ave NW, Washington, DC
                matched: true
                lat: 38.89869893252
                lng: -77.03518753691
                matchedAddress: 1600 PENNSYLVANIA AVE NW, WASHINGTON, DC, 20500
                state: DC
                county_fips: '11001'
                tract: '11001980000'
                block_group: '110019800001'
                matches:
                - query: 1600 Pennsylvania Ave NW, Washington, DC
                  matched: true
                  lat: 38.89869893252
                  lng: -77.03518753691
                  matchedAddress: 1600 PENNSYLVANIA AVE NW, WASHINGTON, DC, 20500
                  state: DC
                  county_fips: '11001'
                  tract: '11001980000'
                  block_group: '110019800001'
        '400':
          description: Invalid address parameter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: INVALID_PARAMETERS
                message: address is required
        '404':
          description: No matching address
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: NO_MATCH
                message: No matching US address was found
                query: not a real address
                matched: false
        '429':
          $ref: '#/components/responses/RateLimited'
          description: Gateway throttling or an address-search limit. Action-based public address searches additionally enforce per-IP minute/day and global day/month caps, so a short retry may not resolve an exhausted daily or monthly allowance. These limits are separate from organization API usage.
        '502':
          description: Census Geocoder unavailable or timed out
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: GEOCODER_UNAVAILABLE
                message: Address lookup is temporarily unavailable
      tags:
      - Geocode
    servers:
    - url: https://api.crimescore.io/v1
      description: Production
    - url: https://api.dev.crimescore.io/v1
      description: Development
components:
  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)
  responses:
    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.
  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