Districts Service Updates - December 16, 2025¶

Summary¶

Major performance improvements to the Districts API. The GeoJSON endpoint now includes party/representative data directly, eliminating the need for per-district wiki calls.

What Changed¶

1. Party Data in GeoJSON Response¶

The /api/v1/districts endpoint now includes party information in each feature's properties.

Before: Client had to make 442 API calls (1 GeoJSON + 441 wiki calls)

After: Client makes 1 API call and gets everything

2. New Properties in GeoJSON Features¶

Each feature now includes:

{
  "type": "Feature",
  "properties": {
    "geoid": "1903",
    "state_fips": "19",
    "district": "03",
    "name": "Iowa's 3rd Congressional District",
    "party": "Republican",
    "representative": "Zach Nunn",
    "cook_pvi": "R+3"
  },
  "geometry": { ... }
}

Property	Type	Description
`party`	string	`"Republican"` or `"Democrat"`
`representative`	string	Current representative's name
`cook_pvi`	string	Cook Partisan Voting Index (e.g., `"R+3"`, `"D+12"`, `"EVEN"`)

3. Redis Caching¶

All endpoints now use Redis caching with ~200x speedup on cache hits: - First request: ~300ms - Cached requests: ~1.5ms

Cache TTLs: - District/state data: 7 days - Wikipedia data: 24 hours

Migration Guide¶

For Map Coloring¶

Old approach (remove this):

// DON'T DO THIS - 441 API calls!
const geojson = await fetch('/api/v1/districts?format=geojson&include_geometry=true');
for (const feature of geojson.features) {
  const wiki = await fetch(`/api/v1/districts/${feature.properties.geoid}/wiki`);
  feature.properties.party = wiki.party;
}

New approach:

// Single request - party data included
const response = await fetch('/api/v1/districts?format=geojson&include_geometry=true&limit=500');
const geojson = await response.json();

// Party data is already in each feature
geojson.features.forEach(feature => {
  const color = feature.properties.party === 'Republican' ? '#E91D0E' : '#232066';
  // Apply color to map layer
});

For District Detail Pages¶

The /wiki endpoint still exists for detailed Wikipedia data:

GET /api/v1/districts/{geoid}/wiki

Use this when you need: - Full Wikipedia summary - County list - Population data - Wikipedia URL

Coverage¶

441 congressional districts with 100% party coverage
All 50 states + DC + territories
Data validated against 119^th Congress (2025-2027)

Endpoints Reference¶

Endpoint	Use Case	Cache TTL
`GET /districts?format=geojson`	Map rendering with party colors	7 days
`GET /districts/{geoid}`	Single district metadata	7 days
`GET /districts/{geoid}/wiki`	Full Wikipedia data	24 hours
`GET /states`	State list	7 days
`GET /states/{code}/districts`	Districts in a state	7 days

Questions?¶

Contact the Districts Service team or check the full API docs at: https://docs.nominate.ai/cbdistricts-docs/district-pages-api/