Skip to main content

Quickstart — Your First API Call in 5 Minutes

This guide walks you from zero to a working API response in five minutes or less.

Step 1: Get an API Key​

Sign up for free → and create a free API key. Keys are prefixed with pck_live_.

Free tier

The Free plan includes 1,000 requests per month. No credit card required.

Early Access

PrairieCloud is in early access. Sign up at dashboard.prairiecloud.io to get your API key.

Step 2: Make Your First Request​

Replace YOUR_API_KEY with your key and run this curl command:

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.prairiecloud.io/v1/data?variables=pop_total&geo=state:48"

This requests the total population of Texas (FIPS code 48) from the latest ACS 5-Year estimates.

Step 3: Understand the Response​

A successful response looks like this:

{
  "data": {
    "state:48": {
      "geo_key": "state:48",
      "name": "Texas",
      "geo_type": "state",
      "fips_state": "48",
      "fips_county": null,
      "geoid_full": null,
      "variables": {
        "pop_total": {
          "api_name": "pop_total",
          "census_code": "B01001_001E",
          "label": "Total population",
          "unit": "count",
          "display_format": "integer",
          "estimate": 30029572,
          "margin_of_error": null,
          "moe_annotation": null,
          "census_annotation": null,
          "suppressed": false,
          "null_reason": null
        }
      }
    }
  },
  "meta": {
    "source": {
      "dataset": "acs5",
      "vintage_year": 2024,
      "reference_period": "2020–2024",
      "census_program": "U.S. Census Bureau"
    },
    "variable_count": 1,
    "geography_count": 1,
    "total_count": null,
    "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "elapsed_ms": 12
  },
  "links": {
    "self": "https://api.prairiecloud.io/v1/data?variables=pop_total&geo=state:48"
  }
}

Key fields:

FieldDescription
data[geo_key].variables[api_name].estimateThe numeric value for this variable + geography
data[geo_key].variables[api_name].margin_of_error90% confidence margin of error (null for non-estimate variables)
data[geo_key].variables[api_name].census_codeThe original Census Bureau variable code (e.g., B01001_001E)
meta.source.vintage_yearThe survey year this data covers
meta.source.reference_periodThe 5-year span, e.g., "2020–2024"
meta.request_idUse this UUID when contacting support about a specific request
meta.elapsed_msServer-side processing time in milliseconds

Query Multiple Variables and Geographies​

You can request multiple variables and geographies in a single call:

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.prairiecloud.io/v1/data?variables=pop_total,income_median_household&geo=state:48,state:06,state:36"

This returns total population and median household income for Texas (48), California (06), and New York (36).

Query Sub-County Data​

PrairieCloud supports census tracts and block groups for granular, neighborhood-level analysis. Every tier can query a specific tract or block group directly by FIPS code. Higher tiers unlock bulk-style workflows: wildcard expansion, boundary access, inline geometry, CSV export, and MCP access.

# Get total population for a specific census tract in Houston
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.prairiecloud.io/v1/data?variables=pop_total&geo=tract:48201311100"

Tract FIPS codes are 11 digits: state (2) + county (3) + tract (6). In this example, 48 = Texas, 201 = Harris County, 311100 = tract number.

You can also use parent geography names instead of FIPS codes — the API resolves them automatically:

# Get total population for ALL tracts in Harris County, Texas
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.prairiecloud.io/v1/data?variables=pop_total&geo=tract:Harris County, Texas"

This resolves "Harris County, Texas" to FIPS 48201 and expands to all matching tracts (equivalent to tract:48201*). Wildcard expansion starts at Pro for tract workflows and Business for block group workflows. See the Smart Geography Resolution section in the Data Guide for more examples.

Use Census Codes​

If you're migrating from the Census Bureau API, you can use Census variable codes directly — no need to look up the PrairieCloud api_name first:

# B01001_001E is the Census code for total population (api_name: pop_total)
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://api.prairiecloud.io/v1/data?variables=B01001_001E&geo=state:48"

The API resolves Census codes automatically and returns the same data as querying by api_name. You can mix Census codes and api_name values in the same request.

Next Steps​