Public specification

Intelligence Score

The RevAddress Intelligence Score is a transparent 0–100 trust rating computed from public US Census data. Every factor is disclosed. Every penalty is itemized on the response. No proprietary black box, no hidden weights, no invented "AI confidence".

If a signal cannot be observed (missing demographics, suppressed ACS data), it is skipped — never imputed. Scores default optimistic, not pessimistic, in the absence of evidence.

Try it live → API reference Get free API key

The formula

Base 100. Each observed risk signal subtracts a fixed penalty. The result is clamped to the 0–100 range 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

There are no multipliers, no hidden adjustments, no ML models. Every penalty in this document is declared in services/usps-api-worker/src/apis/demo.js under TRUST_PENALTIES, and the test suite asserts that every signal the composite emits comes from that map.

Penalties (the complete set)

Every signal the public demo can emit. No others exist. If we add one, this page and the test suite change in the same commit.

Signal	Penalty	Trigger	Source
`geocode_inexact`	−15	`Census Geocoder match_type is not "Exact"` A non-exact match means the Census Geocoder could not rooftop-locate the address. Coordinates are typically interpolated along the street segment, which is fine for zoning but not for shipping risk.	US 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. This is a strong signal of a transient area — abandoned housing, seasonal rentals, or condemned stock — all of which correlate with delivery and identity risk.	ACS 5-year B25001 / B25002
`elevated_tract_vacancy`	−10	`Census tract vacancy_rate in (0.10, 0.20]` Between 10% and 20% vacancy — above the rough national median but not catastrophic. 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. High renter turnover tracts have more address churn, more sublets, more forwarded mail, and more 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. A 5-point nudge reflects that we trust the data less, not that the place itself is risky.	ACS 5-year B01003

Exclusivity rules

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 strict 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 — the score stays 100 from that side.

Letter bands

The score maps to a letter grade. Grades are the human-facing summary; the numeric score is what you should route on for automation.

Score ≥ 90 · high_trust

High-trust address. Rooftop-matched, stable tract, no adverse ACS signals.

Score ≥ 75 · good_trust

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

Score ≥ 60 · moderate_trust

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

Score ≥ 40 · low_trust

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

Score ≥ 0 · not_trusted

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

Data sources

The public demo uses only the two free US Census surfaces below. No paid APIs, no USPS calls, no third-party data brokers on the /api/demo/* path.

US Census Geocoder

Converts a street address into rooftop latitude/longitude plus the census block and tract FIPS codes. Powers the geocode_inexact signal.

Endpoint: geocoding.geo.census.gov

No API key. No cost. US-only.

Census ACS 5-Year (2022)

Tract-level demographic estimates averaged over 2018–2022. Powers vacancy, ownership, and population signals. Suppressed values (−666666666) are treated as missing, not as evidence.

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

No API key. No cost. Public domain.

ACS variables used

Exactly the variables we request, in the exact order we request them. -666666666 is the ACS suppression sentinel and is coerced to 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 small_tract signal.

Sample response

A real captured response for 1 Apple Park Way, Cupertino, CA 95014. Every field is either from the Census Geocoder, Census ACS, or this scoring specification. signals is empty because the tract is stable; when non-empty, each signal appears here with the exact penalty it cost.

{
  "input": {
    "streetAddress": "1 APPLE PARK WAY",
    "city": "CUPERTINO",
    "state": "CA",
    "ZIPCode": "95014"
  },
  "geocode": {
    "coordinates": { "lat": 37.33451, "lng": -122.00898, "accuracy": "rooftop" },
    "census": { "tract": "508107", "block": "1017", "county_fips": "085", "state_fips": "06" },
    "match_type": "Exact",
    "source": "census_geocoder"
  },
  "demographics": {
    "census_tract": "06085508107",
    "demographics": {
      "median_household_income": 186458,
      "population": 5012,
      "housing_units": 1870,
      "vacancy_rate": 0.032,
      "owner_occupied_pct": 0.68,
      "renter_occupied_pct": 0.32,
      "median_year_built": 1988
    },
    "vintage": "2022_acs5",
    "source": "census_acs_5yr"
  },
  "trust": {
    "score": 100,
    "grade": "A",
    "label": "high_trust",
    "description": "High-trust address. Rooftop-matched, stable tract, no adverse ACS signals.",
    "signals": []
  },
  "summary": "This address scored 100/100 (A — high trust). Census Geocoder returned rooftop coordinates. Tract median household income $186,458. Vacancy rate 3.2%. Population 5,012. 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 public demo is intentionally narrow — geocode + ACS + composite. Authenticated production endpoints stack additional USPS-certified signals on top of the same transparent base.

USPS DPV confirmation — the single strongest deliverability signal. Available on /api/address/validate.
CMRA detection — flags commercial mail receiving agencies used as personal addresses.
Address-level vacancy — USPS per-unit vacancy, sharper than the tract-level ACS figure used here.
Secondary-unit recovery — guided recovery when a valid street address is missing an apartment or suite.
ZIP+4 enrichment — exact ZIP+4 plus delivery-point barcode for every confirmed address.
Per-merchant analytics — track dispute rates, return rates, and fraud signals across your own address history.

Get free API key Pricing Try the demo

Integrity

This page is the public contract. The authoritative implementation lives in services/usps-api-worker/src/apis/demo.js and the contract is locked down by services/usps-api-worker/src/apis/demo.test.js. Any change to a penalty value, band threshold, or emitted signal must update all three in the same commit — otherwise tests fail and the change cannot ship.