Skip to content

Intelligence score

A 0–100 trust rating for a US address, computed from two free Census Bureau sources. Each response lists the penalties it applied.

A signal that cannot be observed (missing demographics, suppressed ACS values) is skipped, never imputed, so a gap in the data costs no points.

How the score is computed

Every address starts at 100. Each observed risk signal subtracts a fixed penalty, and the result is clamped to 0–100 and mapped to a letter grade.

score = 100
for signal in observed_signals:
    score -= TRUST_PENALTIES[signal]
score = clamp(score, 0, 100)
grade = band_for(score)  # A ≥ 90, B ≥ 75, C ≥ 60, D ≥ 40, F < 40

The score is that subtraction and nothing else: no multipliers, weights or models. Send an address to /api/demo/intelligence and the response lists each signal beside the score, so any grade can be reproduced by hand.

Every penalty the demo applies

These 5 signals are all the public demo can emit (TRUST_PENALTIES in the serving code).

Signal Penalty Trigger Source
geocode_inexact −15 Census geocoder match_type is not "Exact"

A non-exact match means the Census Geocoder could not tie the address to a specific address range on a street segment. Coordinates fall back to a coarser centroid, which is fine for zoning but not for shipping risk.

Census geocoder
high_tract_vacancy −20 Census tract vacancy_rate > 0.20

More than 20% of housing units in the surrounding census tract are vacant. Vacancy that high points to abandoned housing, seasonal rentals or condemned stock, each of which goes with higher delivery and identity risk.

ACS 5-year B25001 / B25002
elevated_tract_vacancy −10 Census tract vacancy_rate in (0.10, 0.20]

Vacancy above 10% and up to 20%. Applied once, never stacked with high_tract_vacancy.

ACS 5-year B25001 / B25002
low_ownership −10 Census tract owner_occupied_pct < 0.30

Fewer than 30% of occupied homes are owner-occupied. Tracts with high renter turnover see more address churn, sublets, forwarded mail and identity uncertainty.

ACS 5-year B25003
small_tract −5 Census tract population < 500 (and > 0)

Small-tract ACS 5-year estimates carry much higher statistical uncertainty. The 5 points mark lower confidence in the estimate; the place itself is not judged riskier.

ACS 5-year B01003

Edge cases

  • high_tract_vacancy and elevated_tract_vacancy are mutually exclusive. Vacancy is penalized once.
  • A vacancy rate of exactly 0.10 triggers neither: the boundary is strictly greater-than.
  • small_tract requires population < 500 and > 0. A zero-population record is treated as missing data, not a small tract.
  • Missing ACS fields (non-numeric values) produce no signal and cost no points.

Letter bands

Grades are for people reading a report; route automation on the numeric score. The text beside each grade is what the API returns in trust.description.

A
Score ≥ 90 high_trust

High-trust address. Matched exactly on the Census road network, stable tract, no adverse ACS signals.

B
Score ≥ 75 good_trust

Good trust. One or two minor ACS signals — safe to ship with standard verification.

C
Score ≥ 60 moderate_trust

Moderate trust. Collect secondary verification (phone or ID) before high-value shipments.

D
Score ≥ 40 low_trust

Low trust. Multiple risk signals in the tract. Manual review recommended.

F
Score ≥ 0 not_trusted

Do not ship without speaking to the customer. Tract fails multiple stability checks.

Where the data comes from

The /api/demo/* path reads the two free Census Bureau sources below. It makes no USPS calls and buys no third-party data.

Census geocoder

Turns a street address into coordinates on its street segment, with the census block and tract codes. Drives the geocode_inexact signal.

Endpoint: geocoding.geo.census.gov

Free, keyless, US addresses only.

Coordinates are interpolated along the matched TIGER/Line street segment; they are not surveyed to the parcel. The accuracy field names that method (street_interpolated, estimated along the street) and is not a distance guarantee.

Census ACS 5-year (2024)

Tract-level estimates pooled over 2020–2024. Drives the vacancy, ownership and population signals. Suppressed values (−666666666) count as missing data.

Endpoint: api.census.gov/data/2024/acs/acs5

Free, keyless, public domain.

ACS variables we request

Listed in request order. -666666666 is the ACS suppression sentinel; it becomes null before scoring.

Variable Meaning Role in the score
B19013_001E Median household income Informational; not a penalty input.
B25001_001E Total housing units Denominator for vacancy_rate.
B25002_003E Vacant housing units Numerator for vacancy_rate.
B25003_001E Total occupied housing units Denominator for owner_occupied_pct.
B25003_002E Owner-occupied housing units Numerator for owner_occupied_pct.
B25003_003E Renter-occupied housing units Exposed in the response; not a penalty input.
B25035_001E Median year structure built Informational; not a penalty input.
B01003_001E Total population Drives the small_tract signal.

Sample response

Captured from the demo for 1200 Main St, Dallas, TX 75202, the first sample on the live demo, so you can rerun it. Each field comes from the Census geocoder, the ACS or this specification. signals is empty because no penalty applied; when one does, it is listed with the points it cost.

GET /api/demo/intelligence JSON
{
  "input": {
    "streetAddress": "1200 Main St",
    "city": "Dallas",
    "state": "TX",
    "ZIPCode": "75202"
  },
  "geocode": {
    "coordinates": { "lat": 32.779519, "lng": -96.804202, "accuracy": "street_interpolated" },
    "census": { "tract": "003102", "block": "1021", "county_fips": "48113", "county_fips_3": "113", "county_name": "Dallas County", "state_fips": "48" },
    "match_type": "Exact",
    "source": "census_geocoder"
  },
  "demographics": {
    "census_tract": "48113003102",
    "demographics": {
      "median_household_income": 136518,
      "population": 1823,
      "housing_units": 1340,
      "vacancy_rate": 0.084,
      "owner_occupied_pct": 0.386,
      "renter_occupied_pct": 0.614,
      "median_year_built": 1966
    },
    "vintage": "2024_acs5",
    "source": "census_acs_5yr"
  },
  "trust": {
    "score": 100,
    "grade": "A",
    "label": "high_trust",
    "description": "High-trust address. Matched exactly on the Census road network, stable tract, no adverse ACS signals.",
    "signals": []
  },
  "summary": "This address scored 100/100 (A — high trust). Census Geocoder returned street-level coordinates (32.77952, -96.80420). The surrounding census tract has a median household income of $136,518. Tract vacancy rate is 8.4%. Tract population: 1,823. No adverse signals detected.",
  "spec_url": "https://revaddress.com/docs/intelligence-score/",
  "signup_url": "https://revaddress.com/signup",
  "notice": "This is the public demo surface. No API key required. Rate-limited per IP. Production endpoints carry USPS DPV/CMRA/vacancy signals and additional scoring — see /pricing."
}

What production adds

The demo stops at the geocode, the ACS figures and the score. Authenticated production endpoints add USPS signals on top of the same base.

USPS DPV confirmation
Whether USPS confirms the address as a delivery point. Returned by /api/address/validate with a paid plan and purchased credits.
CMRA detection
Flags a commercial mail receiving agency (a private mailbox store) given as a personal address.
Address-level vacancy
USPS vacancy for the delivery point itself, sharper than the tract-level ACS figure used here.
Secondary-unit recovery
Guided recovery when a valid street address is missing its apartment or suite.
ZIP+4 enrichment
The exact ZIP+4 and delivery-point barcode for every confirmed address.
Per-merchant analytics
Dispute rates, return rates and fraud signals across your own address history.

Scores match the serving code

The penalties and band cutoffs on this page are the values the serving code uses. The worker's tests lock the scoring, and after every deploy a check compares the demo's sample address with a live call. A score that differs from the tables above is a bug: email support@revaddress.com.