City scores in one request
A REST API that returns source-backed scores for any city we cover, from the same reviewed release that powers our dashboards.
# Scores for San Ramon, CA
curl https://app.citycites.io/api/intelligence/v1/cities/CA/san-ramon/scores \
-H "Authorization: Bearer $CITYCITES_KEY"Getting started
- Get a key. Request access. Keys are issued to partners and shown once, so store yours somewhere safe.
- Send it with every request in the
Authorization: Bearer <key>header (orX-API-Key). - Call an endpoint. All responses are JSON and name the release and methodology version they came from.
Base URL: https://app.citycites.io/api/intelligence/v1
Endpoints
| Request | Returns |
|---|---|
GET/meta | The release being served: methodology version, as-of date, states covered, sources. |
GET/cities/{state} | Every scored city in a state, with headline scores. |
GET/cities/{state}/{city}/scores | One city: every score with its components, peer percentile, completeness, confidence and sources. |
{state} is a two-letter code such as CA. {city} is the city's slug from the state list, such as san-ramon.
Response
Headline values for San Ramon, CA. Partner responses also include each score's components, sources and source dates.
{
"release": "2027.3-...",
"methodology_version": "2027.3",
"as_of": "2026-11",
"city": {
"city": "San Ramon",
"state": "CA",
"fips_place": "0668378",
"as_of": "2026-11",
"peer_group": "50k-150k residents",
"scores": {
"growth": {
"value": 54,
"peer_percentile": 54,
"confidence": "high",
"data_completeness": 1.0
},
"climate_investment": {
"value": 37,
"peer_percentile": 18,
"confidence": "high",
"data_completeness": 1.0
},
"transparency": {
"value": 64,
"peer_percentile": 16,
"confidence": "medium",
"data_completeness": 1.0
},
"community_investment": {
"value": 37,
"peer_percentile": 19,
"confidence": "medium",
"data_completeness": 0.7
},
"diversity_index": {
"value": 64,
"display_policy": "research",
"confidence": "high",
"data_completeness": 1.0
}
},
"data_completeness": 0.94,
"methodology_version": "2027.3"
}
}
The Demographic Diversity Index always carries display_policy: "research" and is never ranked. Display policy
The political lean indicator (indicators.political_lean) is returned only to keys with the political scope, granted after a partner agrees in writing not to use it for housing, lending, insurance, employment or advertising decisions. It carries display_policy: "descriptive" and is never ranked.
Errors
Errors return JSON: {"error": {"code": "...", "message": "..."}}.
| Status | Code | What to do |
|---|---|---|
401 | missing_key | No API key was sent. Add the Authorization header. |
401 | invalid_key | The key is wrong or was revoked. Contact us for a new one. |
404 | state_not_covered | There are no scores for that state yet. The message lists covered states. |
404 | city_not_found | No scored city with that name in the state. List the state's cities to find its slug. |
429 | rate limited | More than 120 requests a minute or 20,000 a day for one key. Wait and retry. |
503 | release_unavailable | Scores are being updated. Retry in a few minutes. |
Limits & coverage
- 120 requests a minute and 20,000 a day per key. Ask us if you need more.
- Coverage: 8,099 US cities: every city with 1,800 or more residents in all 50 states and DC, plus every California city.
- Scores update when a new reviewed release is published.
/metatells you which release you are reading.
Other ways to get the data
| Delivery | Best for |
|---|---|
| Bulk data files CSV / Parquet, available on request | Data warehouses, models, research teams |
| Embedded components City score widgets, in development | Fast launch without front-end work |
Ready to build?
Tell us about your product and we'll issue a key.