Concepts

Ask for the thing, not the source. A concept is a plain word — population, gdp, median_income, median_home_value, unemployment_rate — that works anywhere an indicator code does. Creative Foresight chooses which underlying series answers it for each kind of place, and every response tells you exactly which series that was.

curl "https://api.creativeforesight.io/v1/observations?indicator=population&region=47187" \
  -H "Authorization: Bearer cf_live_REPLACE_ME"

{
  "data": [{ "period_start": "2025-01-01", "value": 272061, ... }],
  "meta": {
    "indicator": "population_total",
    "region": "47187",
    "concept": {
      "code": "population",
      "resolved_indicator": "population_total",
      "source": "census"
    }
  }
}

How resolution works

• Exact indicator codes always win. If you ask for UNRATE or census.b25077_001e.y, you get exactly that series — concepts never intercept a real code.
• Concepts resolve by place kind. The same concept can map to different series for a county, a state, the US, or another country. gdp for Germany answers from the World Bank’s annual series; gdp for the US answers from FRED’s richer quarterly series. The choice is editorial — that’s the point — and meta.concept always discloses it.
• Concepts require a region. A concept is a question about a place.
• Honest refusals. If a concept isn’t curated for the kind of place you asked about, you get a clear 404: “‘gdp’ isn’t available at the county level; the closest available is national.” — never a coarser number dressed up as your region.
• Data that isn’t loaded yet may return 202 with Retry-After, exactly like any other request for a series being prepared — retry with the indicator named in the envelope, or just repeat your concept request.

Current concepts

Derived concepts

Some concepts are measures no source publishes — we compute them. employment_rate (employed residents as a share of the labor force) is the first: ask for it like any concept, and the response’s meta.concept.inputs discloses every underlying series that fed the calculation.

"concept": {
  "code": "employment_rate",
  "resolved_indicator": "cf:employment_rate.47187",
  "source": "creative-foresight",
  "inputs": { "employed": "employed", "labor_force": "labor_force" }
}

If any ingredient isn’t available for the kind of place you asked about, the refusal names it: “‘employment_rate’ isn’t available at the national level; its employed input is only available at the county level.”

Concepts in /v1/ask

Natural-language questions resolve to concepts first, deterministically — ask “what’s the population of Williamson County?” twice and both answers cite the same series, because the choice is a registry lookup, not model judgment.

Concepts work on every read endpoint — observations, latest, insights, signals, and panel — and the catalog grows as we curate more. Each entry carries a documented selection rationale on our side.