Skip to main content

Changelog

All notable changes to the PrairieCloud API are documented here. This project follows Semantic Versioning.

[1.2.0] — 2026-04-04​

Added​

  • Business tier ($299/mo) — New tier between Pro and Enterprise. 2M requests/month, 3,000/min burst, 50 concurrent connections, 50 API keys. Includes block group wildcard expansion, block group boundaries, priority email support (4-hour response), and 20m+5m boundary resolutions. Does not include custom bulk boundary delivery or 500k resolution (Enterprise-only).
  • 5-tier pricing model — Full tier lineup is now Free ($0) → Pioneer ($19) → Pro ($49) → Business ($299) → Enterprise (custom). The Business tier fills the gap between Pro and Enterprise for teams that need block group wildcard/boundary workflows and higher limits without an enterprise contract.

Changed​

  • MCP and geography workflow access now align with the 5-tier product model — MCP access is available on Pioneer, Pro, Business, and Enterprise. Within MCP, direct tract/block group lookup is available on MCP-enabled plans; tract wildcard/geometry workflows require Pro+ and block-group wildcard/geometry workflows require Business+.
  • Pro tier support response time relaxed from 4-hour to 24-hour priority email
  • product.json version bumped to v2.0.0 to reflect the 5-tier pricing model
  • Variable topics reorganized into 9 topics: core, demographics, economics, environment, equity, health, housing, social, transport (was 6)

Removed​

  • early_access_datasets feature flag removed from product configuration — all datasets are now generally available

[1.1.0] — 2026-04-03​

Added​

  • Smart Geography Resolution — Query sub-geography types using parent names instead of FIPS codes. tract:Harris County, Texas automatically resolves to tract:48201*, expanding to all tracts in Harris County. Works for tract, block_group, and county types with state or county parent names. State abbreviations (TX) and full names (Texas) both supported.
  • Metro area smart resolution — Query tracts, block groups, and counties by metro area name. tract:Dallas-Fort Worth resolves the metro, looks up its 11 component counties via a CBSA-to-county crosswalk table, and expands all tracts across those counties. block_group:Austin returns all block groups in the Austin metro. county:Dallas-Fort Worth returns all component counties. Works for all 935 CBSAs (metropolitan and micropolitan statistical areas).
  • Congressional district smart resolution — Query tracts, block groups, and counties by congressional district. tract:TX-7 resolves to all tracts in Texas Congressional District 7 via a CD-to-tract crosswalk table (90,467 mappings across all 444 districts, 118th Congress). Supports shorthand format (TX-7), full state name (Texas-7), and fuzzy name lookup (Congressional District 7, Texas). 4,868 tracts that straddle two CDs are included in both.
  • Geocode endpoint (GET /v1/geocode) — Resolve an address or lat/lng coordinates to all containing Census geographies (block group, tract, county, metro, congressional district, state, nation). Address geocoding via Census Bureau geocoder; coordinate lookup via PostGIS spatial queries against 331,000+ boundary polygons. Available to all tiers (Free+).
  • Geocode MCP tool (geocode) — MCP tool exposing the geocode endpoint. Enables natural-language location-based Census queries (e.g., "What's the median income near downtown Austin?" → geocode → get_census_data).
  • Children endpoint (GET /v1/geographies/{geo_key}/children) — Discover child geographies for any parent. Supports direct children (state → county) and deep hierarchies via FIPS prefix (state → tract). Tier-aware pagination with standard APIResponse envelope. Parent geo key supports name resolution (e.g., /v1/geographies/state:TX/children).
    • Valid parent → child types: nation → state, state → county/cd/tract/block_group, metro → county/tract/block_group, cd → county/tract/block_group, county → tract/block_group, tract → block_group
    • Metro parent example: GET /v1/geographies/metro:19100/children?type=county returns all counties in the Dallas-Fort Worth metro
    • CD parent example: GET /v1/geographies/cd:4807/children?type=tract returns all tracts in Texas CD 7

Notes​

  • Smart geo resolution is now complete across all 7 geography types — nation, state, county, metro, congressional district, tract, and block group all work as parents.
  • Smart geo resolution uses wildcard expansion under the hood — the same tier-based expansion limits apply.
  • Metro resolution uses a CBSA-to-county crosswalk table (not FIPS prefix matching) since metros span non-contiguous counties.
  • CD resolution uses a CD-to-tract crosswalk table (not FIPS prefix matching) since congressional districts span tracts across multiple counties.

[1.0.0] — 2026-04-02​

Breaking Changes​

  • Complete variable catalog overhaul: 1,861 variables replaced with 392 curated variables from 53 B/C-tables. The new catalog is focused on variables needed for composite index computation (SVI, ADI, EJScreen, etc.)
  • All variable api_name values changed from verbose Census-derived names to topic-prefixed human-readable names:
    • sex_and_age_total_population → pop_total
    • income_and_benefits_total_households_median_household_income_dollars → income_median_household
    • housing_occupancy_total_housing_units → housing_total_units
    • employment_status_population_16_years_and_over_in_labor_force → employ_in_labor_force
    • Full mapping available via the variable detail endpoint
  • Data Profile tables (DP02–DP05) removed in favor of underlying Detailed Tables (B/C-tables), which use stable Census codes that don't renumber between releases

Added​

  • Tract geography support: 85,396 census tracts with observation data, boundaries, and centroids. Direct tract data is available on all tiers; tract wildcard expansion, boundaries, and centroids require Pro tier and above. Tract data available for ACS 5-Year vintages 2017–2024.
  • Block group geography support: 242,297 block groups with observation data and boundaries. Direct block group data is available on all tiers; block group wildcard expansion, boundaries, and centroids require Business tier and above. Block group data available for ACS 5-Year vintages 2017–2024.
  • Census code alias resolution: Query variables by Census code (e.g., B01001_001E) in addition to api_name. Census codes and api_name values can be mixed in the same request.
  • census_code field in variable list and detail responses, mapping each api_name to its Census Bureau variable code
  • 901.6 million total observations across 35 vintages (up from 152.9M)
  • 331,559 GeoJSON boundaries across all 7 geography levels (state, county, metro, CD, nation, tract, block group)
  • MCP server documentation — Quickstart guide and tool reference for connecting Claude Desktop, Cursor, and other MCP-compatible AI assistants to PrairieCloud Census data. See MCP Quickstart and MCP Tool Reference.

Changed​

  • Variable count: 1,861 → 392 (focused on composite index computation: SVI, ADI, EJScreen, etc.)
  • Geography count: ~4,650 → 392,435 (7 levels including tract and block group)
  • Database: 42 GB → 218 GB
  • Wildcard limits updated: Pro 5,000, Business 25,000, Enterprise 50,000; Free/Pioneer retain internal expansion guards but do not include wildcard access
  • product.json version 1.0.0 → 1.1.0
  • Boundary and wildcard geography tiering revised: direct data lookup is available at every geography level; boundary/wildcard workflows follow Free (nation/state boundaries), Pioneer (+county/metro/CD boundaries), Pro (+tract wildcard/boundaries), Business (+block_group wildcard/boundaries), Enterprise (500k resolution plus custom bulk boundary delivery)
  • Variable topics reorganized: core (238), housing (85), transport (26), equity (19), health (14), environment (10)

[0.16.0] — 2026-03-25​

Added​

  • Annual billing — Pioneer ($190/yr) and Pro ($490/yr) plans with ~17% discount (2 months free)
  • Monthly/annual toggle on dashboard billing page and website pricing page
  • interval parameter on POST /v1/account/checkout (default: "monthly", also accepts "annual")
  • Stripe catalog bootstraps 4 prices (Pioneer/Pro × monthly/annual)

Changed​

  • Refund policy per ToS v1.1 §8.2: annual fee minus monthly rate per month used

[0.15.0] — 2026-03-24​

Added​

  • MCP Server at mcp.prairiecloud.io — Model Context Protocol server for AI/LLM access to Census data
  • 7 tools at launch: get_census_data, compare_geographies, get_timeseries, search_variables, search_geographies, list_topics, list_datasets (8th tool geocode added in v1.1.0)
  • Launch-time tier gating: Pioneer, Pro, Enterprise (Free tier blocked). Business tier was added later in v1.2.0.
  • Auth via API key (Bearer header), Redis-cached tier validation
  • Streamable HTTP transport, FastMCP framework
  • Server instructions guide LLMs on effective Census data querying

[0.14.0] — 2026-03-24​

Added​

  • Geo boundary endpoints — GeoJSON boundary data for states, counties, metros, and congressional districts
    • GET /v1/boundaries/{identifier} — boundary shapes
    • GET /v1/centroids/{geo_type} — geographic center points
  • Boundary collections served through /v1/boundaries/{identifier} with 20m, 5m, and Enterprise 500k resolution support where available
  • Tier-based boundary access introduced; current boundary and resolution tiers are documented in the latest tier tables above

Security​

  • Cloudflare Turnstile on contact form (fail-open, token validated and discarded)
  • API origin IP hidden behind Cloudflare proxy (api.prairiecloud.io now proxied)
  • Caddy trusted_proxies updated for all Cloudflare IPv4 ranges

[0.13.0] — 2026-03-24​

Added​

  • GeoJSON boundary endpoints — Retrieve geographic boundary shapes for states, counties, metros, congressional districts, and the nation. Three resolution tiers matching Census cartographic boundary conventions: 20m (default), 5m (detailed), 500k (enterprise).
  • GET /v1/boundaries/{geo_type} — GeoJSON FeatureCollection for all geographies of a type
  • GET /v1/boundaries/{geo_key} — Single GeoJSON Feature
  • GET /v1/centroids/{geo_type} — Lightweight centroid points for dot maps
  • include_geometry=true on GET /v1/data — Returns data AND boundary shapes in one API call. Build choropleth maps with a single request. Pro tier and above.
  • Enterprise custom boundary delivery for approved high-resolution bulk use cases
  • ETag/If-None-Match support for efficient client-side caching (304 Not Modified)
  • X-Boundary-Vintage: 2024 response header on all boundary responses

Changed​

  • Fixed cd type alias — congressional district wildcards (cd:48*) and type filters (?type=cd) now work correctly
  • Boundary endpoints are free (0 cost units) for the tier that has access
  • Tier-based boundary access introduced; current boundary and resolution tiers are documented in the latest tier tables above

[0.12.0] — 2026-03-22​

Changed​

  • Wildcard geography limits increased for then-current Pro and Enterprise tiers. Current limits are documented in the latest tier tables above.

[0.11.0] — 2026-03-21​

Added​

  • CSV export (format=csv): Export data from /v1/data, /v1/compare, and /v1/timeseries as CSV. Pro tier and above. Includes formula injection protection and 10,000 row cap.
  • Wildcard geography queries (geo=county:48*): Expand to all matching geographies. Pro tier and above. Current tier limits are documented in the latest tier tables above.
  • Topics endpoint (GET /v1/topics): List all variable topics with counts of active variables.
  • Static codebook: Download the complete variable catalog at /v1/codebook.json (1.4MB) or /v1/codebook.csv (577KB). Served as static files with 24-hour cache.
  • Census code search: Search variables by Census Bureau code (e.g. ?search=DP05_0001E). Returns matched Census codes with vintage availability.
  • Enhanced 429 responses: Rate limit errors now include plan name, quota limit, and upgrade URL.
  • Variable coverage hints: Empty search results and ACS 1-Year geographic mismatches include contextual guidance in the hint field.
  • Tier-aware pagination: /v1/variables and /v1/geographies support higher limits for Pro (5,000) and Enterprise (10,000).

Changed​

  • Connection pool increased from 6 to 15 per worker (30 total)
  • Rate limit cost now scales with wildcard expansion (Pro+ only)
  • RFC 7807 error responses standardized across all billing endpoints
  • OpenAPI spec regenerated with all new endpoints and parameters

Fixed​

  • Billing 401 responses now include application/problem+json content type, WWW-Authenticate header, and instance field
  • Rate limit cost calculation: multi-geo/variable requests now correctly charge >1 unit
  • Stale tier tests updated to 4-tier structure

[0.10.0] — 2026-03-20​

Changed​

  • Pricing restructure: 5 tiers → 4. Added Pioneer ($19/mo), removed Business ($299) and Power ($499)
  • New tier structure: Free → Pioneer ($19) → Pro ($49) → Enterprise (custom)
  • Pioneer tier: 50,000 requests/month, 300/minute burst, 10 concurrent
  • Pro tier: 500,000 requests/month, 1,500/minute burst, 25 concurrent (previously Business limits)

[0.9.0] — 2026-03-15​

Added — Detailed Tables (B Tables)​

  • 813 new variables from 30 core Detailed Table (B table) groups — demographics, income, education, housing, employment, health insurance, language, and disability
    • Loaded across all 35 vintages (ACS 5-Year 2009–2024 + ACS 1-Year 2005–2024, excluding 2020)
    • ~66.7 million new observations added
  • Total catalog: 1,861 variables (1,048 Data Profile + 813 Detailed Tables)
  • Total observations: 141.6 million (up from 74.9M)
  • Margin of error data (moe_numeric, moe_annotation) now included for Detailed Table variables

Changed​

  • Data guide updated with Detailed Tables overview, B table topic breakdown, and revised variable counts
  • Core Concepts updated to reflect expanded catalog
  • API introduction updated to reference both ACS products and table types
  • llms.txt updated with current variable and observation counts

Internal​

  • Database migrated to partitioned schema: acs.observations with year partitions (acs.observations_2005 through acs.observations_2024)
  • Audit tables added: audit.etl_runs, audit.etl_table_loads
  • Storage: ~34.6 GB used, ~93 GB free

[0.8.0] — 2026-03-11​

Added — Legal Compliance & Data Retention​

  • Terms of Service acceptance — Users must agree to the ToS and acknowledge the Privacy Policy before using the API
    • New endpoint: POST /v1/account/accept-tos — records acceptance with full audit trail (IP, user agent, timestamp, document version)
    • API key requests now check ToS acceptance version; outdated acceptance returns HTTP 403 after a 30-day grace period
    • Signup page displays legal acceptance text with links to Terms of Service and Privacy Policy
  • Data retention enforcement — Automated daily cleanup enforcing Privacy Policy retention periods:
    • Deleted accounts: hard-purge 30 days after soft-delete
    • API usage logs: purge after 24 months
    • IP address logs: anonymize after 12 months
    • Support communications: purge after 3 years
    • Billing records: 7 years (tax law, manual review only)
    • Full audit trail of all retention-based deletions

Changed​

  • OpenAPI spec updated to v0.8.0 (25 endpoints, was 22)
  • API description updated to reflect both ACS 5-Year and 1-Year datasets

Documentation​

  • Data Guide — Added variable coverage matrix by vintage, PrairieCloud vs Census Bureau API comparison section
  • Core Concepts — Updated to reflect both ACS 5-Year and 1-Year datasets, corrected vintage ranges
  • Legal pages — Terms of Service (tos-v1.0) and Privacy Policy (pp-v1.0) updated with version headers and technical details

[0.7.1] — 2026-03-08​

Fixed — Variable Mapping Accuracy​

  • Critical fix: Rebuilt all variable-to-vintage mappings using label-based matching instead of code-based matching
    • Census Bureau reassigns DP table code numbers between releases (e.g., DP05_0017E = "Median age" in 2009 but "85 years and over" in 2023)
    • Previous data had some variables mapped to incorrect concepts for older vintages
    • All 74.9 million observations reloaded with verified-correct per-vintage mappings
  • Variable coverage varies by vintage — older vintages have fewer available variables because Census restructured table definitions over time
    • 2023: 100% of variables available
    • 2019–2022: 82–91%
    • 2013–2018: 63–75%
    • 2009–2012: 31–64%
    • 2005–2008: 14–64%
  • ACS 1-Year expanded to 19 vintages: 2005–2024 (excluding 2020)
    • Added 2005–2009 historical data (2005 uses DP01→DP05 crosswalk)

Changed​

  • Total observations: 74.9 million (52.8M ACS 5-Year + 22.1M ACS 1-Year) across 35 vintages
  • Row count reduced from previous 102M due to stricter variable matching — only variables with verified-correct label matches are loaded

[0.7.0] — 2026-03-07​

Added — ACS 1-Year Estimates​

  • New dataset: acs1 — American Community Survey 1-Year Estimates now available
    • 14 vintages: 2010–2024 (2020 excluded — not released due to COVID data collection disruptions)
    • Covers geographies with 65,000+ population (nation, states, 854 counties, 530 metros, 437 congressional districts)
  • Usage: GET /v1/data?dataset=acs1&vintage=2023&variables=pop_total&geo=state:48
  • Key difference from ACS 5-Year: 1-Year estimates reflect a single year's data (more current but higher margins of error), while 5-Year combines five years (more reliable for small areas)
  • Status page — branded with PrairieCloud theme, API-only monitoring at status.prairiecloud.io

Changed​

  • "Status" links renamed to "API Status" across website, docs, and dashboard
  • Dashboard login page updated with latest logo and white background

[0.6.0] — 2026-03-02​

Added — Production Readiness (M7)​

  • Automated deployments — GitHub Actions workflows for staging and production
    • Staging auto-deploys on develop merge (after CI passes)
    • Production deploys on main merge with manual approval gate
    • Automatic rollback if health check fails after production deploy
  • Structured JSON logging — every request logged with structlog
    • Request tracing via X-Request-ID header (generated or propagated)
    • Fields: method, path, status_code, duration_ms, client_ip, user_agent
    • Log levels: INFO (2xx/3xx), WARNING (4xx), ERROR (5xx)
    • /health excluded to reduce noise
  • Monitoring & alerting — health checks every 2 minutes, disk usage alerts
  • Database backups — daily automated PostgreSQL backups with 7-day/4-week retention
  • Security headers — CSP, Permissions-Policy added to existing HSTS/X-Frame/X-Content-Type

Changed​

  • Staging environment live at staging-api.prairiecloud.io
  • OpenAPI spec regenerated from v0.5.2 endpoints

Internal​

  • Infrastructure repo initialized with backup/restore scripts, monitoring, runbooks
  • 10 new unit tests for request logging middleware (307 total)
  • Deployment runbook: docs/DEPLOYMENT.md

[0.5.2] — 2026-03-02​

Added — QA Hardening (M6)​

  • 297 automated tests (was 138) — 115% increase in test coverage
    • 65 security boundary tests: API key auth, JWT validation, rate limiting, CORS enforcement, SQL injection prevention, webhook signature verification
    • 55 integration tests: full-stack tests against real PostgreSQL + Redis (not mocks)
    • 29 contract tests: automated OpenAPI spec validation ensuring API responses match documented schemas
    • k6 load test baseline: p95 latency = 18ms at 25 concurrent users
  • CI pipeline enhanced: schema initialization, isolated test runs, 10-minute timeout guard
  • Production database schema fix: unique constraint on customers.key_id (migration 007)

Internal​

  • CI now runs 3 separate test suites: unit/security, integration, contract
  • Load test scripts available at tests/load/baseline.js for ongoing performance monitoring
  • All test infrastructure committed to repo — new contributors can run the full suite locally

[0.5.1] — 2026-03-01​

Added​

  • 16 ACS 5-Year vintages — complete historical coverage from 2009 through 2024 (was 3 vintages)
  • 75.7 million observations in the database (was 14.8M)
  • Variable-vintage mappings for all 16 years — the API knows exactly which variables exist in each vintage
  • /v1/timeseries now returns up to 16 data points per variable/geography
  • Variable Catalog Overview in data guide — 46 curated key variables across all 4 topics with exact api_name values, plus at-a-glance topic summary table

Changed​

  • Default vintage remains the most recent (2024)
  • /v1/datasets endpoint now reflects all 16 vintages in counts and metadata

Notes​

  • Schema deltas handled: 641 core variables are available across all vintages. 55 additional variables were added incrementally by the Census Bureau between 2009–2024. Variables that don't exist in a given vintage return null in timeseries responses.
  • No breaking changes — existing API calls continue to work identically.

[0.5.0-beta] — 2026-02-28​

Added​

  • Developer Dashboard at dashboard.prairiecloud.io
    • API key management (create, rotate, revoke)
    • Usage monitoring with daily request charts
    • Billing and plan management via Stripe
    • Account settings
  • Compare endpoint (GET /v1/compare) — side-by-side comparison of multiple geographies for the same variable(s)
  • Timeseries endpoint (GET /v1/timeseries) — track a variable across vintages
  • 11 account management endpoints (/v1/account/*) — profile, keys, usage, billing
  • Invite code activation (POST /v1/account/activate) — private beta access
  • Clerk authentication for dashboard sign-in (Google OAuth + email/password)
  • R code examples in documentation (httr2)
  • Full API reference auto-generated from OpenAPI spec (22 endpoints)
  • Local search on docs site

Changed​

  • API expanded from 9 to 22 endpoints
  • Rate limit headers included on all authenticated responses
  • CORS restricted to specific origins and headers
  • Tier limits table updated with concurrency limits

Fixed​

  • Usage tracking now records and displays real request counts
  • Webhook event deduplication corrected (Svix ID from headers)
  • API response links.self now uses https:// behind reverse proxy

Security​

  • OpenAPI docs (/docs, /redoc) disabled in production
  • JWT issuer validation enforced
  • CSP headers on dashboard
  • DEBUG=false in production

[0.1.0] — 2026-02-27​

Initial release of the PrairieCloud API.

Added​

API Endpoints

  • GET /v1/data — query ACS 5-Year observations by variable and geography
  • GET /v1/variables — browse and search the variable catalog
  • GET /v1/variables/{api_name} — variable detail with vintage availability
  • GET /v1/geographies — browse geographies by type, parent, or name
  • GET /v1/geographies/{geo_key} — geography detail with parent hierarchy
  • GET /health — service health check
  • POST /v1/account/checkout — Stripe Checkout session
  • GET /v1/account/portal — Stripe Customer Portal
  • GET /v1/account/usage — billing period usage statistics

Data

  • ACS 5-Year Estimates: vintages 2022, 2023, 2024
  • 4,650 geographies (nation, states, counties, metros, congressional districts)
  • 1,084 variables (542 estimate + 542 percent)
  • 14.8M observations (4.3 GB)

Authentication & Rate Limiting

  • API key auth via X-API-Key header (format: pck_live_ + 32 chars)
  • Five tiers: Free, Pro ($49/mo), Business ($299/mo), Power ($499/mo), Enterprise (custom)
  • Three-layer rate limiting: monthly quota, per-minute burst, concurrent connections
  • RFC 7807 error responses with request_id for support tracing

Documentation

  • docs.prairiecloud.io launched
  • Guides: quickstart, authentication, data, rate limiting, error handling
  • Code examples: cURL, Python, JavaScript

Historical Roadmap Note​

At this point in the product history, future candidates under consideration included:

  • Additional Detailed Tables (B/C tables) based on usage demand
  • SDK libraries for Python and JavaScript
  • Webhook notifications for billing events
  • Population Estimates Program (PEP) dataset
  • Bureau of Labor Statistics (BLS) data
  • Bureau of Economic Analysis (BEA) data

Questions? Email [email protected] or open an issue on GitHub.