The Indicators endpoints serve curated, normalized data. But the platform ingests far more series than it curates. The Discovery catalog gives you access to the full raw inventory from every connected provider.
When to use Discovery vs. Indicators
Use Indicators when you want clean, comparable data with standardized metadata, release tracking, and vintage support.
Use Discovery when you're looking for a specific provider series that hasn't been curated yet, or when you want to browse the full breadth of what's available.
Searching the catalog
curl -G https://macrobymark.com/api/indicators/discover \
--data-urlencode "q=consumer price index" \
--data-urlencode "provider=eurostat" \
-H "X-API-Key: YOUR_KEY"
Discovery search ranks matches using source metadata, geography, indicator context, and quality signals from the catalog.
For user-facing search, preferredCountry can be passed as a low-cost
personalization hint. It prefers matching country results without narrowing the
result set. Use country instead when the result set must be country-scoped.
Available filters
| Parameter | Effect |
|---|---|
q | Full-text query against series title and metadata. |
provider | Restrict to a single provider code (e.g. oecd, ecb, bls). |
country | Restrict to a country code (ISO-2, e.g. US, DE, or EA20). |
preferredCountry | Prefer a country in ranking without filtering. Ignored when explicit geography is present. |
topic | Restrict to a canonical concept key (e.g. consumer_price_index). |
indicator | Restrict to a curated indicator slug. |
frequency | Restrict to a frequency (daily, monthly, quarterly, annual). |
subdivision | Restrict to a subnational region by ISO 3166-2 or NUTS code. Aliased as state for backward compatibility. |
limit | Page size (default 30). |
browse | Set to all to retrieve top entries when no filters are active. |
Filtering by subnational region
Subdivision filtering is the way to retrieve series at state, province, or NUTS-region granularity from providers that publish below the national level (BLS regional CPI, Eurostat NUTS-1 unemployment, BEA regional GDP, StatCan provincial accounts, etc.):
curl -G https://macrobymark.com/api/indicators/discover \
--data-urlencode "country=US" \
--data-urlencode "subdivision=US-CA" \
--data-urlencode "topic=consumer_price_index" \
-H "X-API-Key: YOUR_KEY"
Subdivision codes follow the ISO 3166-2 standard for most countries
(e.g. US-CA, CA-ON, AU-NSW) and use Eurostat's NUTS codes for EU
member states (FR1, DE2, IT5).
The discovery catalog currently enriches subdivisions for these classification systems:
- US states, U.S. census regions and divisions, U.S. metro areas
- EU NUTS-1, NUTS-2, NUTS-3
- Canadian provinces and territories
- Australian states and territories
- Japanese prefectures
- Mexican states
- South Korean provinces
- and additional systems as adapter coverage grows
The indicator detail page surfaces these subdivisions automatically through a cascading selector that appears below the country switcher when subnational data exists for the selected (country, indicator) pair.
Requesting curation
Found a series you need in the curated layer? Submit a curation request:
curl -X POST https://macrobymark.com/api/indicators/curation-requests \
-H "X-API-Key: YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"provider": "eurostat", "seriesKey": "PRC_HICP_MANR__CP00__M__EU"}'
Curation requests are reviewed and prioritized by demand.