---
title: "Neighborhood distress index for a tract, block group or county"
method: GET
path: "/api/v1/neighborhood/distress"
tags: ["Market"]
---

# Neighborhood distress index for a tract, block group or county

`GET /api/v1/neighborhood/distress`

## Request

- Base URL: `https://propraven.com`
- URL: `https://propraven.com/api/v1/neighborhood/distress`
- Auth: HTTP bearer

Area-level neighborhood distress index (census tract / block group, never an address) for value-add and turnaround screening. Give exactly one of `geoid` (11-digit tract: the tract plus its block groups; 12-digit block group: the block group plus its parent tract) or `county_fips` (a screening list; `level`, `order`, `min_score`, `limit` max 100, `offset`). `score` is 0-100, higher = more distressed, from the national components; `score_local` adds tax delinquency, code violations and foreclosure where a local source covers the area and is null elsewhere. Every component carries its status, source and as-of date; missing / suppressed / not_covered components are left out of the score, never zero. Every answer carries the method (weights, missing-component rule), the sources and the county's coverage. Requires an account (API key, MCP OAuth token or signed-in session) and is metered like the other analytics reads; an anonymous caller gets 401 and nothing is read. Before the index's first load the answer is 503 `distress_index_unavailable`.

## Query parameters

- `geoid` string
- `county_fips` string
- `level` 'tract' | 'block_group'
- `order` 'score_desc' | 'score_asc'
- `min_score` number
- `limit` integer
- `offset` integer

## Response `200`

The area (geoid) or the county screening list (county_fips).

- union
  - NeighborhoodDistressArea: One tract (with its block groups, compact) or one block group (with its parent tract).
    - `schema_version` 'neighborhood-distress-v1', required
    - `layer_version` string, required
    - `built_at` string, nullable, required
    - `method` DistressMethod, required
      - `version` string, required
      - `weights` object, required: The published component weights.
      - `missing_components` string, required
      - `scale` string, required
      - `score` string, required
      - `score_local` string, required
    - `notes` string[], required
    - `sources` DistressSource[], required
      - `component` string, required
      - `kind` string, required
      - `native_geo_level` string, required
      - `weight` number, nullable, required
      - `source_id` string, required
      - `title` string, required
      - `publisher` string, required
      - `source_url` string, required
      - `as_of` string, date, nullable, required
      - `vintage` string, required
      - `method_note` string, required
      - `coverage_note` string, required
      - `n_tracts_with_value` integer, required
      - `n_block_groups_with_value` integer, required
    - `coverage` DistressCoverage[], required
      - `county_fips` string, required
      - `state_fips` string, required
      - `component` string, required
      - `n_tracts` integer, required
      - `n_tracts_with_value` integer, required
      - `n_block_groups` integer, required
      - `n_block_groups_with_value` integer, required
      - `note` string, nullable, required
    - `query` object, required
      - `geoid` string, required
    - `geo_level` 'tract' | 'block_group', required
    - `area` DistressArea, required: The index for one census tract or block group. Area-level: it describes the neighborhood, never an address or a person.
      - `geo_level` 'tract' | 'block_group', required
      - `geoid` string, required
      - `state_fips` string, required
      - `county_fips` string, required
      - `tract_geoid` string, required
      - `score` number, nullable, required: 0-100, higher = more distressed; national components only. Null with null_reason when the core ACS components are missing.
      - `score_percentile` number, nullable, required
      - `score_local` number, nullable, required: National plus local components (tax delinquency, code violations, foreclosure) where a local source covers the area; null where none does (never a copy of score).
      - `score_local_reason` string, nullable, required
      - `weight_coverage` number, nullable, required: Share of the published national weight whose component has a value here (1 = all present).
      - `local_weight_coverage` number, nullable, required
      - `n_components` integer, nullable, required
      - `missing_components` string[], required
      - `null_reason` string, nullable, required
      - `as_of_min` string, date, nullable, required
      - `as_of_max` string, date, nullable, required
      - `components` DistressComponent[], required
        - `component` string, required
        - `label` string, required
        - `kind` string, nullable, required: national | local | flag
        - `status` 'ok' | 'missing' | 'suppressed' | 'not_covered' | 'inherited_tract', required
        - `value` number, nullable, required
        - `unit` string, nullable, required
        - `percentile` number, nullable, required: National percentile of the value (0-100); null when there is no value.
        - `weight` number, nullable, required
        - `geo_level` string, nullable, required: tract | block_group | county: the level the source publishes.
        - `source_id` string, nullable, required
        - `publisher` string, nullable, required
        - `source_url` string, nullable, required
        - `as_of` string, date, nullable, required
        - `note` string, required
    - `parent_tract` DistressArea, required: The index for one census tract or block group. Area-level: it describes the neighborhood, never an address or a person.
      - `geo_level` 'tract' | 'block_group', required
      - `geoid` string, required
      - `state_fips` string, required
      - `county_fips` string, required
      - `tract_geoid` string, required
      - `score` number, nullable, required: 0-100, higher = more distressed; national components only. Null with null_reason when the core ACS components are missing.
      - `score_percentile` number, nullable, required
      - `score_local` number, nullable, required: National plus local components (tax delinquency, code violations, foreclosure) where a local source covers the area; null where none does (never a copy of score).
      - `score_local_reason` string, nullable, required
      - `weight_coverage` number, nullable, required: Share of the published national weight whose component has a value here (1 = all present).
      - `local_weight_coverage` number, nullable, required
      - `n_components` integer, nullable, required
      - `missing_components` string[], required
      - `null_reason` string, nullable, required
      - `as_of_min` string, date, nullable, required
      - `as_of_max` string, date, nullable, required
      - `components` DistressComponent[], required
        - `component` string, required
        - `label` string, required
        - `kind` string, nullable, required: national | local | flag
        - `status` 'ok' | 'missing' | 'suppressed' | 'not_covered' | 'inherited_tract', required
        - `value` number, nullable, required
        - `unit` string, nullable, required
        - `percentile` number, nullable, required: National percentile of the value (0-100); null when there is no value.
        - `weight` number, nullable, required
        - `geo_level` string, nullable, required: tract | block_group | county: the level the source publishes.
        - `source_id` string, nullable, required
        - `publisher` string, nullable, required
        - `source_url` string, nullable, required
        - `as_of` string, date, nullable, required
        - `note` string, required
    - `block_groups` object[], nullable, required
      - `geoid` string, required
      - `score` number, nullable, required
      - `score_local` number, nullable, required
      - `null_reason` string, nullable, required
  - NeighborhoodDistressCounty: A county screening list, score order, unscored areas last.
    - `schema_version` 'neighborhood-distress-v1', required
    - `layer_version` string, required
    - `built_at` string, nullable, required
    - `method` DistressMethod, required
      - `version` string, required
      - `weights` object, required: The published component weights.
      - `missing_components` string, required
      - `scale` string, required
      - `score` string, required
      - `score_local` string, required
    - `notes` string[], required
    - `sources` DistressSource[], required
      - `component` string, required
      - `kind` string, required
      - `native_geo_level` string, required
      - `weight` number, nullable, required
      - `source_id` string, required
      - `title` string, required
      - `publisher` string, required
      - `source_url` string, required
      - `as_of` string, date, nullable, required
      - `vintage` string, required
      - `method_note` string, required
      - `coverage_note` string, required
      - `n_tracts_with_value` integer, required
      - `n_block_groups_with_value` integer, required
    - `coverage` DistressCoverage[], required
      - `county_fips` string, required
      - `state_fips` string, required
      - `component` string, required
      - `n_tracts` integer, required
      - `n_tracts_with_value` integer, required
      - `n_block_groups` integer, required
      - `n_block_groups_with_value` integer, required
      - `note` string, nullable, required
    - `query` object, required
      - `county_fips` string, required
      - `level` 'tract' | 'block_group', required
      - `order` 'score_desc' | 'score_asc', required
      - `min_score` number
      - `limit` integer, required
      - `offset` integer, required
    - `count` integer, required
    - `total` integer, required
    - `next_offset` integer, nullable, required
    - `results` DistressArea[], required
      - `geo_level` 'tract' | 'block_group', required
      - `geoid` string, required
      - `state_fips` string, required
      - `county_fips` string, required
      - `tract_geoid` string, required
      - `score` number, nullable, required: 0-100, higher = more distressed; national components only. Null with null_reason when the core ACS components are missing.
      - `score_percentile` number, nullable, required
      - `score_local` number, nullable, required: National plus local components (tax delinquency, code violations, foreclosure) where a local source covers the area; null where none does (never a copy of score).
      - `score_local_reason` string, nullable, required
      - `weight_coverage` number, nullable, required: Share of the published national weight whose component has a value here (1 = all present).
      - `local_weight_coverage` number, nullable, required
      - `n_components` integer, nullable, required
      - `missing_components` string[], required
      - `null_reason` string, nullable, required
      - `as_of_min` string, date, nullable, required
      - `as_of_max` string, date, nullable, required
      - `components` DistressComponent[], required
        - `component` string, required
        - `label` string, required
        - `kind` string, nullable, required: national | local | flag
        - `status` 'ok' | 'missing' | 'suppressed' | 'not_covered' | 'inherited_tract', required
        - `value` number, nullable, required
        - `unit` string, nullable, required
        - `percentile` number, nullable, required: National percentile of the value (0-100); null when there is no value.
        - `weight` number, nullable, required
        - `geo_level` string, nullable, required: tract | block_group | county: the level the source publishes.
        - `source_id` string, nullable, required
        - `publisher` string, nullable, required
        - `source_url` string, nullable, required
        - `as_of` string, date, nullable, required
        - `note` string, required

## Other responses

- `400`: Invalid parameter (`code: invalid_parameter`).
- `401`: Missing, malformed or invalid credential.
- `404`: No index row for this geoid in the current release (`code: geography_not_found`).
- `405`: The endpoint exists but does not support this method. `Allow` lists the methods it does.
- `429`: Rate limit exceeded.
- `500`: Unexpected server error. The body never carries database or driver text.
- `503`: The data behind this endpoint is temporarily unavailable. Honour `Retry-After` when present.

---

[API](https://skmtc.dev/propraven/apis/propraven-api.md) · [All operations](https://skmtc.dev/propraven/apis/propraven-api/llms.txt) · [OpenAPI document](https://skmtc.dev/propraven/apis/propraven-api/revisions/37f8158c4eda?raw)