crimescore-io Score API

openapi: 3.2.0
info:
  title: Crimescore Io Score API
  version: '1.0'
  contact:
    name: CrimeScore Support
    url: https://crimescore.io
  license:
    name: Proprietary
  description: 'Operations tagged Score 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: Score
paths:
  /score:
    get:
      operationId: getScore
      summary: Get safety score for a location
      description: 'Returns the CrimeScore Safety Score for either an exact coordinate pair or a

        ZIP code estimate resolved through a Census ZCTA. Provide exactly one input mode: `lat` + `lng`, or

        `zip`. Coordinate requests resolve to the containing Census block group.

        ZIP requests resolve to a population-weighted Census ZCTA rollup, which

        is less precise than an exact coordinate. All successful `/score`

        responses include score, grade, resolved geography, component scores,

        and model metadata.

        Use `/score/details` with eligible evaluation access that includes score

        details, or a paid Starter or higher tier, to request contributor

        explanations for the overall score or a specific component.'
      parameters:
      - name: lat
        in: query
        required: false
        description: Latitude (-90 to 90). Required when using coordinate lookup.
        schema:
          type: number
          format: float
          minimum: -90
          maximum: 90
        example: 40.7128
      - name: lng
        in: query
        required: false
        description: Longitude (-180 to 180). Required when using coordinate lookup.
        schema:
          type: number
          format: float
          minimum: -180
          maximum: 180
        example: -74.006
      - name: zip
        in: query
        required: false
        description: 5-digit ZIP code, resolved as a Census ZIP Code Tabulation Area (ZCTA)
        schema:
          type: string
          pattern: ^\d{5}$
        example: '10001'
      responses:
        '200':
          description: Score found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScoreResponse'
              examples:
                coordinate:
                  summary: Coordinate score response
                  value:
                    geoid: '360610031002'
                    resolved:
                      lat: 40.7128
                      lng: -74.006
                      state: NY
                      county_fips: '061'
                    safety_score: 28
                    safety_grade: D
                    components:
                      violent_crime: 24.8
                      property_crime: 37.9
                      disorder: 29.2
                      frequency: 31.5
                    data:
                      census_vintage: '2024'
                      model_version: '2.0'
                zcta:
                  summary: ZIP code response
                  value:
                    zcta: '10001'
                    resolved:
                      zip: '10001'
                    safety_score: 39
                    safety_grade: D
                    components:
                      violent_crime: 42
                      property_crime: 36
                      disorder: 37
                      frequency: 40
                    data:
                      census_vintage: '2024'
                      model_version: '2.0'
                      block_group_count: 42
        '400':
          description: Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid_coordinates:
                  summary: Invalid coordinate input
                  value:
                    error: INVALID_PARAMETERS
                    message: Invalid lat/lng parameters
                mixed_inputs:
                  summary: ZIP and coordinate inputs cannot be mixed
                  value:
                    error: INVALID_PARAMETERS
                    message: Provide either zip or lat/lng parameters, not both
                invalid_zip:
                  summary: Invalid ZIP input
                  value:
                    error: INVALID_PARAMETERS
                    message: zip must be exactly 5 digits
        '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: Score 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
        '404':
          description: No data for location
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                no_coverage:
                  summary: Coordinates or ZIP code outside available coverage
                  value:
                    error: NO_COVERAGE
                    message: No score data for this ZIP code
                    zip: '99999'
                no_score:
                  summary: Block group found but no score data
                  value:
                    error: NO_SCORE_DATA
                    message: No score data for block group
                    geoid: '360610031002'
        '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:
      - Score
    servers:
    - url: https://api.crimescore.io/v1
      description: Production
    - url: https://api.dev.crimescore.io/v1
      description: Development
  /score/details:
    get:
      operationId: getScoreDetails
      summary: Get score contributor details
      description: 'Returns the selected score/component explanation for either an exact

        coordinate or a ZIP code estimate. This endpoint requires eligible

        evaluation access that includes score details, or a paid Starter or higher

        tier. It defaults `component` to `overall` and returns the available

        contributor list for that selected component using

        `{ label, direction, impact }`.'
      parameters:
      - name: lat
        in: query
        required: false
        description: Latitude (-90 to 90). Required when using coordinate lookup.
        schema:
          type: number
          format: float
          minimum: -90
          maximum: 90
        example: 40.7128
      - name: lng
        in: query
        required: false
        description: Longitude (-180 to 180). Required when using coordinate lookup.
        schema:
          type: number
          format: float
          minimum: -180
          maximum: 180
        example: -74.006
      - name: zip
        in: query
        required: false
        description: 5-digit ZIP code resolved as a Census ZIP Code Tabulation Area (ZCTA). Provide either `zip` or `lat` + `lng`, not both.
        schema:
          type: string
          pattern: ^\d{5}$
        example: '10001'
      - name: component
        in: query
        required: false
        description: Score component to explain. Defaults to `overall`.
        schema:
          $ref: '#/components/schemas/ScoreComponent'
        example: property_crime
      responses:
        '200':
          description: Score details found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScoreDetailsResponse'
              examples:
                overall:
                  summary: Overall score details
                  value:
                    geoid: '360610031002'
                    resolved:
                      lat: 40.7128
                      lng: -74.006
                      state: NY
                      county_fips: '061'
                    component: overall
                    safety_score: 28
                    safety_grade: D
                    contributors:
                    - label: Higher population density
                      direction: lowers_safety_score
                      impact: high
                      comparison: above_reference
                      value_display: 18,420/sq km
                      reference_display: 1,120/sq km
                      reference_label: National median
                    - label: More vacant homes
                      direction: lowers_safety_score
                      impact: medium
                      comparison: above_reference
                      value_display: 9.6%
                      reference_display: 6.1%
                      reference_label: National median
                    data:
                      census_vintage: '2024'
                      model_version: '2.0'
                component:
                  summary: Property-crime component details
                  value:
                    geoid: '360610031002'
                    resolved:
                      lat: 40.7128
                      lng: -74.006
                      state: NY
                      county_fips: '061'
                    component: property_crime
                    safety_score: 37.9
                    safety_grade: D
                    contributors:
                    - label: More vacant homes
                      direction: lowers_safety_score
                      impact: high
                      comparison: above_reference
                      value_display: 9.6%
                      reference_display: 6.1%
                      reference_label: National median
                    - label: Higher median household income
                      direction: raises_safety_score
                      impact: medium
                      comparison: above_reference
                      value_display: $118,500
                      reference_display: $74,200
                      reference_label: National median
                    data:
                      census_vintage: '2024'
                      model_version: '2.0'
                zcta:
                  summary: ZIP code component details
                  value:
                    zcta: '10001'
                    resolved:
                      zip: '10001'
                    component: property_crime
                    safety_score: 36
                    safety_grade: D
                    contributors:
                    - label: More vacant homes
                      direction: lowers_safety_score
                      impact: high
                      comparison: above_reference
                      value_display: 8.9%
                      reference_display: 6.1%
                      reference_label: National median
                    - label: Higher median household income
                      direction: raises_safety_score
                      impact: medium
                      comparison: above_reference
                      value_display: $112,300
                      reference_display: $74,200
                      reference_label: National median
                    data:
                      census_vintage: '2024'
                      model_version: '2.0'
                      block_group_count: 42
        '400':
          description: Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                invalid_component:
                  summary: Invalid component
                  value:
                    error: INVALID_PARAMETERS
                    message: component must be one of overall, violent_crime, property_crime, disorder, frequency
                mixed_inputs:
                  summary: ZIP and coordinate inputs cannot be mixed
                  value:
                    error: INVALID_PARAMETERS
                    message: Provide either zip or lat/lng parameters, not both
        '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: Score Details 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: Current paid access does not include score details
                  value:
                    error: FORBIDDEN
                    message: Score details are available on Starter and higher tiers
        '404':
          description: No data for location or component
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Score
    servers:
    - url: https://api.crimescore.io/v1
      description: Production
    - url: https://api.dev.crimescore.io/v1
      description: Development
components:
  schemas:
    CoordinateScoreResponse:
      type: object
      required:
      - geoid
      - resolved
      - safety_score
      - safety_grade
      - components
      - data
      properties:
        geoid:
          type: string
          description: Census block group FIPS code (12 digits)
          example: '360610031002'
        resolved:
          type: object
          required:
          - lat
          - lng
          - state
          - county_fips
          description: Resolved coordinate lookup metadata
          properties:
            lat:
              type: number
              description: Input latitude
            lng:
              type: number
              description: Input longitude
            state:
              type: string
              description: State abbreviation
              example: NY
            county_fips:
              type: string
              description: 3-digit county FIPS code
              example: '061'
        safety_score:
          type: integer
          minimum: 0
          maximum: 100
          description: 'Safety score: 0 (lowest safety) to 100 (highest safety)'
        safety_grade:
          type: string
          enum:
          - A
          - B
          - C
          - D
          - F
          description: 'Letter grade: A (safest) through F (most dangerous)'
        components:
          type: object
          description: Sub-score breakdown returned by `/score`
          additionalProperties:
            type: number
          example:
            violent_crime: 24.8
            property_crime: 37.9
            disorder: 29.2
            frequency: 31.5
        data:
          type: object
          required:
          - census_vintage
          - model_version
          properties:
            census_vintage:
              type: string
              description: Identifier for the public context-data release used by this scoring release
              example: '2024'
            model_version:
              type: string
              description: Scoring model version
              example: '2.0'
    ScoreDetailsResponse:
      oneOf:
      - $ref: '#/components/schemas/CoordinateScoreDetailsResponse'
      - $ref: '#/components/schemas/ZctaScoreDetailsResponse'
    CoordinateScoreDetailsResponse:
      type: object
      required:
      - geoid
      - resolved
      - component
      - safety_score
      - safety_grade
      - contributors
      - data
      properties:
        geoid:
          type: string
          description: Census block group FIPS code (12 digits)
          example: '360610031002'
        resolved:
          type: object
          required:
          - lat
          - lng
          - state
          - county_fips
          properties:
            lat:
              type: number
            lng:
              type: number
            state:
              type: string
              example: NY
            county_fips:
              type: string
              example: '061'
        component:
          $ref: '#/components/schemas/ScoreComponent'
        safety_score:
          type: number
          minimum: 0
          maximum: 100
          description: Selected overall or component score
          example: 28
        safety_grade:
          type: string
          enum:
          - A
          - B
          - C
          - D
          - F
          description: Letter grade for the selected score/component
          example: D
        contributors:
          type: array
          description: Available contributor factors for the selected score/component (eligible evaluation access or paid Starter tier and higher)
          items:
            $ref: '#/components/schemas/TopContributor'
        data:
          type: object
          required:
          - census_vintage
          - model_version
          properties:
            census_vintage:
              type: string
              description: Identifier for the public context-data release used by this scoring release
              example: '2024'
            model_version:
              type: string
              example: '2.0'
    TopContributor:
      type: object
      required:
      - label
      - direction
      - impact
      properties:
        label:
          type: string
          description: Human-readable local factor based on the observed feature value versus the release reference
          example: More residents below poverty level
        comparison:
          type: string
          enum:
          - below_reference
          - near_reference
          - above_reference
          description: Whether the observed feature value is below, near, or above the scoring-release reference
          example: above_reference
        value_display:
          type: string
          description: Compact display value for the selected geography
          example: 18.4%
        reference_display:
          type: string
          description: Compact display value for the scoring-release reference
          example: 12.1%
        reference_label:
          type: string
          description: Public description of the comparison reference
          example: National median
        observations:
          type: array
          maxItems: 2
          description: Valid observed conditions that clarify a grouped factor when no single member represents it
          items:
            $ref: '#/components/schemas/ContributorObservation'
        direction:
          type: string
          enum:
          - lowers_safety_score
          - raises_safety_score
          description: 'Enum describing whether this local factor lowers or raises the safety score. Values: `lowers_safety_score`, `raises_safety_score`.'
          example: lowers_safety_score
        impact:
          type: string
          enum:
          - high
          - medium
          - low
          description: 'Enum describing relative modeled impact among the returned contributors. Values: `high`, `medium`, `low`.'
          example: high
    ScoreComponent:
      type: string
      enum:
      - overall
      - violent_crime
      - property_crime
      - disorder
      - frequency
      description: Score component that can be explained by `/score/details`
    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)
    ZctaScoreResponse:
      type: object
      description: 'ZIP code estimate computed as a population-weighted rollup of covered

        Census block-group scores. ZCTAs are Census approximations of USPS ZIP

        delivery areas, so this response is less precise than a coordinate

        lookup and is not a direct observed crime rate for a USPS ZIP route.

        '
      required:
      - zcta
      - resolved
      - safety_score
      - safety_grade
      - components
      - data
      properties:
        zcta:
          type: string
          description: Census ZIP Code Tabulation Area code
          example: '10001'
        resolved:
          type: object
          required:
          - zip
          description: Resolved ZIP code lookup metadata
          properties:
            zip:
              type: string
              description: Input ZIP code resolved as a Census ZCTA
              example: '10001'
        safety_score:
          type: integer
          minimum: 0
          maximum: 100
          description: 'Estimated safety score: 0 (lowest safety) to 100 (highest safety)'
        safety_grade:
          type: string
          enum:
          - A
          - B
          - C
          - D
          - F
          description: 'Estimated letter grade: A (safest) through F (most dangerous)'
        components:
          type: object
          description: Population-weighted component rollups returned by `/score`
          additionalProperties:
            type: number
          example:
            violent_crime: 42
            property_crime: 36
            disorder: 37
            frequency: 38
        data:
          type: object
          required:
          - census_vintage
          - model_version
          - block_group_count
          properties:
            census_vintage:
              type: string
              description: Identifier for the public context-data release used by this scoring release
              example: '2024'
            model_version:
              type: string
              description: Scoring model version
              example: '2.0'
            block_group_count:
              type: integer
              description: Number of scored block groups used in the ZIP code estimate
              example: 42
    ScoreResponse:
      oneOf:
      - $ref: '#/components/schemas/CoordinateScoreResponse'
      - $ref: '#/components/schemas/ZctaScoreResponse'
    ContributorObservation:
      type: object
      required:
      - label
      - comparison
      - value_display
      - reference_display
      properties:
        label:
          type: string
          description: Observed condition within a grouped model factor
          example: Fewer married-couple households
        comparison:
          type: string
          enum:
          - below_reference
          - near_reference
          - above_reference
          example: below_reference
        value_display:
          type: string
          description: Compact display value for the selected geography
          example: 35.8%
        reference_display:
          type: string
          description: Compact display value for the scoring-release reference
          example: 47.7%
        reference_label:
          type: string
          description: Public description of the comparison reference
          example: National median
    ZctaScoreDetailsResponse:
      type: object
      required:
      - zcta
      - resolved
      - component
      - safety_score
      - safety_grade
      - contributors
      - data
      properties:
        zcta:
          type: string
          description: Census ZIP Code Tabulation Area code
          example: '10001'
        resolved:
          type: object
          required:
          - zip
          properties:
            zip:
              type: string
              description: Input ZIP code resolved as a Census ZCTA
              example: '10001'
        component:
          $ref: '#/components/schemas/ScoreComponent'
        safety_score:
          type: number
          minimum: 0
          maximum: 100
          description: Selected overall or population-weighted component score
          example: 36
        safety_grade:
          type: string
          enum:
          - A
          - B
          - C
          - D
          - F
          description: Letter grade for the selected score/component
          example: D
        contributors:
          type: array
          description: Weighted contributor factors for the selected ZIP code score/component (eligible evaluation access or paid Starter tier and higher)
          items:
            $ref: '#/components/schemas/TopContributor'
        data:
          type: object
          required:
          - census_vintage
          - model_version
          - block_group_count
          properties:
            census_vintage:
              type: string
              description: Identifier for the public context-data release used by this scoring release
              example: '2024'
            model_version:
              type: string
              example: '2.0'
            block_group_count:
              type: integer
              description: Number of scored block groups used in the ZIP code estimate
              example: 42
  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.
  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