Skip to main content

cURL Examples

Copy and paste these examples directly. Replace YOUR_API_KEY with your actual key from dashboard.prairiecloud.io.

Setup​

Set your API key as a shell variable to keep examples clean:

export PCKEY="pck_live_YOUR_KEY_HERE"

Single Variable Lookup​

Fetch the total population for Texas (FIPS 48):

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

Multi-Variable Query​

Fetch multiple variables for multiple geographies in one request:

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

This returns total population, median household income, and owner-occupied housing units for Texas, California, and New York — all in a single request.

Browse the Variable Catalog​

Search for variables by keyword:

# Search for income-related variables
curl -H "X-API-Key: $PCKEY" \
  "https://api.prairiecloud.io/v1/variables?search=income&limit=10"

# Filter by unit (dollar, count, percent, year)
curl -H "X-API-Key: $PCKEY" \
  "https://api.prairiecloud.io/v1/variables?unit=dollar&limit=20"

# Paginate with offset
curl -H "X-API-Key: $PCKEY" \
  "https://api.prairiecloud.io/v1/variables?limit=50&offset=50"

Get Variable Detail​

Get full detail for a specific variable, including vintage availability:

curl -H "X-API-Key: $PCKEY" \
  "https://api.prairiecloud.io/v1/variables/income_median_household"

Browse Geography Catalog​

Find geographies by type, name, or parent:

# All states
curl -H "X-API-Key: $PCKEY" \
  "https://api.prairiecloud.io/v1/geographies?type=state"

# All counties in Texas (parent = state:48)
curl -H "X-API-Key: $PCKEY" \
  "https://api.prairiecloud.io/v1/geographies?type=county&parent=state:48&limit=50"

# Search by name
curl -H "X-API-Key: $PCKEY" \
  "https://api.prairiecloud.io/v1/geographies?search=harris"

Pretty-Print JSON Output​

Pipe through python3 -m json.tool or jq for readable output:

curl -s -H "X-API-Key: $PCKEY" \
  "https://api.prairiecloud.io/v1/data?variables=pop_total&geo=state:48" \
  | python3 -m json.tool

Or with jq (if installed):

curl -s -H "X-API-Key: $PCKEY" \
  "https://api.prairiecloud.io/v1/data?variables=pop_total&geo=state:48" \
  | jq '.data."state:48".variables.pop_total.estimate'
# → 30029572

Check API Health​

curl https://api.prairiecloud.io/health

Check Your Usage​

curl -H "X-API-Key: $PCKEY" \
  "https://api.prairiecloud.io/v1/account/usage"

Handling Errors​

Check the HTTP status code with -i (include headers) or -w "%{http_code}":

# Print status code only
curl -s -o /dev/null -w "%{http_code}" \
  -H "X-API-Key: $PCKEY" \
  "https://api.prairiecloud.io/v1/data?variables=bad_variable&geo=state:48"
# → 404

# Print full response with headers
curl -i -H "X-API-Key: $PCKEY" \
  "https://api.prairiecloud.io/v1/data?variables=pop_total&geo=state:48"

Next Steps​