GET /providers

The Alphacast provider API gives you a unified interface to discover and navigate data from dozens of official statistical agencies, central banks, and financial data sources. You can list all providers, inspect their capabilities, browse hierarchical category trees, search for specific series within a provider, and manage the provider API keys that some sources require.

Authentication

All provider endpoints use HTTP Basic Auth. Pass your Alphacast API key as the username with an empty password.

curl -u YOUR_API_KEY: https://api.alphacast.io/providers

Most listing and browse endpoints work without authentication, but authenticated requests are required to manage provider API keys via /user-keys.

Endpoints

Returns the full catalog of available data providers. Use this to discover slugs, understand each provider’s capabilities, and check licensing terms before fetching data.

curl -u YOUR_API_KEY: https://api.alphacast.io/providers

import requests

response = requests.get(
    "https://api.alphacast.io/providers",
    auth=("YOUR_API_KEY", ""),
)
providers = response.json()

const response = await fetch("https://api.alphacast.io/providers", {
  headers: { Authorization: "Basic " + btoa("YOUR_API_KEY:") },
});
const providers = await response.json();

Response fields

string

required

Unique identifier for the provider. Use this as the {slug} path parameter in all other provider endpoints. Examples: fred, bls, worldbank, bcra.

string

required

Human-readable name of the data collection. Examples: FRED Economic Data, BLS Public Data.

string

required

Name of the organization that publishes the data. Examples: Federal Reserve Bank of St. Louis, U.S. Bureau of Labor Statistics.

string

required

Short description of what the provider covers — topics, geography, and data types.

string[]

required

List of supported operations for this provider. Possible values:

"hierarchical" — supports category browsing via GET /providers/{slug}/browse
"search" — supports free-text series search via GET /providers/{slug}/search
"direct" — supports fetching a series directly by ID

string

Data license or usage terms. Examples: Public Domain, Creative Commons Attribution 4.0 (CC-BY 4.0).

Example response

[
  {
    "slug": "fred",
    "name": "FRED Economic Data",
    "provider": "Federal Reserve Bank of St. Louis",
    "description": "Hundreds of thousands of economic time series from dozens of national, international, public, and private sources.",
    "capabilities": ["search", "hierarchical", "direct"],
    "license": "Public Domain (mostly)"
  },
  {
    "slug": "worldbank",
    "name": "World Bank Open Data",
    "provider": "The World Bank",
    "description": "Global development indicators covering economics, health, education, environment, and more for 200+ countries.",
    "capabilities": ["hierarchical", "direct"],
    "license": "Creative Commons Attribution 4.0 (CC-BY 4.0)"
  },
  {
    "slug": "bls",
    "name": "BLS Public Data",
    "provider": "U.S. Bureau of Labor Statistics",
    "description": "Employment, wages, inflation, and productivity statistics from the U.S. federal statistical agency.",
    "capabilities": ["hierarchical", "search", "direct"],
    "license": "Public Domain"
  }
]

GET /providers/match

Performs a keyword search across all providers and returns the top 5 matches with full detail. This endpoint is designed for programmatic discovery — for example, when you want to find which provider carries a certain type of data without knowing its slug in advance. Query parameters

string

required

Free-text search query. Matched against each provider’s slug, name, organization name, and description. Multiple words are scored independently — a provider matching more terms ranks higher.

curl -u YOUR_API_KEY: \
  "https://api.alphacast.io/providers/match?q=argentina+inflation"

Response fields Each item in the returned array includes all fields from /providers plus the following additional fields when the provider requires an API key:

object[]

List of configurable parameters for the provider (same structure as in provider detail).

object[]

Curated list of commonly used series IDs and labels for this provider.

boolean

Present and true when the provider requires you to supply your own API key from the upstream source.

boolean

Present when api_key_required is true. Indicates whether you have already saved an API key for this provider via /user-keys/{slug}.

string

Human-readable label for the key field, such as "FRED API Key" or "INEGI API Token".

string

Message explaining any access limitations when no key is provided. Example: "A FRED API key is required. Get one for free.".

GET /providers/

Returns full detail for a single provider including its configurable parameters, a curated list of popular series, and whether you have a stored API key for it. Path parameters

string

required

Provider slug. Use the slug field from GET /providers. Matching is case-insensitive — fred, FRED, and Fred all resolve to the same provider.

curl -u YOUR_API_KEY: https://api.alphacast.io/providers/fred

Response fields

string

required

Provider slug.

string

required

Display name.

string

required

Publishing organization name.

string

required

Description of the data covered.

string[]

required

Supported operations: "hierarchical", "search", "direct".

object[]

Provider-specific parameters you can pass when fetching series data. Each parameter object includes:

Show parameter properties

string

Parameter key to use in the request body or query string.

string

Human-readable label.

string

Input type: "number", "text", "select".

string

Where the parameter is sent: "body", "query", or "header".

string | number

Default value when not specified.

object[]

For "select" type parameters, the list of allowed values. Each entry has code and label.

object[]

Curated series suggestions. Each item has id (the series ID) and label (a descriptive name).

string

Data license.

string

URL where you can register for an API key with the upstream provider, if applicable.

string

Label for the API key field.

string

Message describing rate limits or access restrictions without a key.

string

Display name for the root level of the provider’s category tree. Example: "Categories" for FRED, "Topics" for World Bank.

string

Example series ID format for this provider. Example: "e.g. GDP, UNRATE, CPIAUCSL" for FRED.

boolean

required

Whether your account has a stored API key for this provider. Always present; false when you are unauthenticated.

Example response

{
  "slug": "fred",
  "name": "FRED Economic Data",
  "provider": "Federal Reserve Bank of St. Louis",
  "description": "Hundreds of thousands of economic time series from dozens of national, international, public, and private sources.",
  "capabilities": ["search", "hierarchical", "direct"],
  "parameters": [
    {
      "key": "units",
      "label": "Units",
      "type": "select",
      "location": "query",
      "default": "lin",
      "values": [
        {"code": "lin", "label": "Levels"},
        {"code": "chg", "label": "Change"},
        {"code": "pch", "label": "% Change"},
        {"code": "pc1", "label": "% Change from Year Ago"},
        {"code": "log", "label": "Log"}
      ]
    },
    {
      "key": "frequency",
      "label": "Frequency",
      "type": "select",
      "location": "query",
      "default": "",
      "values": [
        {"code": "", "label": "Native (no resampling)"},
        {"code": "a", "label": "Annual"},
        {"code": "q", "label": "Quarterly"},
        {"code": "m", "label": "Monthly"}
      ]
    }
  ],
  "popular_series": [
    {"id": "GDP", "label": "Gross Domestic Product"},
    {"id": "UNRATE", "label": "Unemployment Rate"},
    {"id": "CPIAUCSL", "label": "Consumer Price Index for All Urban Consumers"},
    {"id": "FEDFUNDS", "label": "Federal Funds Effective Rate"},
    {"id": "DGS10", "label": "10-Year Treasury Constant Maturity Rate"}
  ],
  "license": "Public Domain (mostly)",
  "api_key_url": "https://fred.stlouisfed.org/docs/api/api_key.html",
  "api_key_label": "FRED API Key",
  "anonymous_limit_message": "A FRED API key is required. Get one for free.",
  "browse_root_label": "Categories",
  "series_id_placeholder": "e.g. GDP, UNRATE, CPIAUCSL",
  "has_user_api_key": true
}

GET /providers//browse

Navigates the hierarchical category structure of a provider. Only available for providers with the "hierarchical" capability. Use this to drill down through topics, surveys, or indicator categories before fetching individual series.

Calling this endpoint on a provider without the "hierarchical" capability returns a 400 error. Check the capabilities array in GET /providers before using browse.

Path parameters

string

required

Provider slug.

Query parameters

string

default:""

Slash-separated navigation path within the provider’s category tree. Omit or leave empty to start from the root. Example: "National Accounts/GDP".

number

default:"1"

How many levels of the tree to prefetch in a single request. Maximum is 3. Use depth=1 (the default) to retrieve only the immediate children of the current path.

boolean

When true, returns paginated series at the current path instead of sub-folders.

number

default:"200"

Page size when series=true. Maximum is 1000.

number

default:"0"

Pagination offset when series=true.

# Browse the root of the World Bank topic tree
curl -u YOUR_API_KEY: \
  "https://api.alphacast.io/providers/worldbank/browse"

# Navigate into a specific topic, two levels deep
curl -u YOUR_API_KEY: \
  "https://api.alphacast.io/providers/worldbank/browse?path=Economy%20%26%20Growth&depth=2"

Example response (root browse)

[
  {"label": "Economy & Growth", "path": "Economy & Growth"},
  {"label": "Education", "path": "Education"},
  {"label": "Energy & Mining", "path": "Energy & Mining"},
  {"label": "Environment", "path": "Environment"},
  {"label": "Financial Sector", "path": "Financial Sector"},
  {"label": "Health", "path": "Health"},
  {"label": "Social Development", "path": "Social Development"}
]

GET /providers//search

Searches for series within a specific provider by keyword. Only available for providers with the "search" capability. Path parameters

string

required

Provider slug.

Query parameters

string

required

Search query string. Returns {"items": []} when the query is empty.

curl -u YOUR_API_KEY: \
  "https://api.alphacast.io/providers/fred/search?q=unemployment+rate"

Response fields

string

required

The search query that was submitted.

object[]

required

Array of matching series. Each item typically includes the series ID and a descriptive label. The exact structure depends on the provider’s search implementation.

Example response

{
  "query": "unemployment rate",
  "items": [
    {"id": "UNRATE", "label": "Unemployment Rate"},
    {"id": "UNRATENSA", "label": "Unemployment Rate (Not Seasonally Adjusted)"},
    {"id": "LNS14000006", "label": "Unemployment Rate - Black or African American"},
    {"id": "LNS14000003", "label": "Unemployment Rate - Hispanic or Latino"}
  ]
}

User API key management

Some providers — such as FRED, INEGI, and BLS — require you to register for an API key directly with the upstream data source. You can store that key in your Alphacast account so it is applied automatically whenever you fetch data from that provider.

GET /user-keys

Returns which providers you currently have API keys stored for. The actual key values are masked; only presence is indicated.

This endpoint requires authentication. Unauthenticated requests will fail.

curl -u YOUR_API_KEY: https://api.alphacast.io/user-keys

Example response

{
  "fred": true,
  "bls": true
}

Each key in the response object is a provider slug. A value of true means you have a stored key for that provider.

PUT /user-keys/

Saves or deletes your API key for a specific provider. Send the key as api_key in the JSON body. Send null or an empty string to remove a previously stored key. Path parameters

string

required

Provider slug. Must match an existing provider in the catalog.

Request body

string

Your API key for the upstream provider. Pass null or omit the field to delete the stored key.

# Save a FRED API key
curl -u YOUR_API_KEY: \
  -X PUT https://api.alphacast.io/user-keys/fred \
  -H "Content-Type: application/json" \
  -d '{"api_key": "your-fred-api-key-here"}'

# Remove the stored FRED API key
curl -u YOUR_API_KEY: \
  -X PUT https://api.alphacast.io/user-keys/fred \
  -H "Content-Type: application/json" \
  -d '{"api_key": null}'

import requests

# Save a FRED API key
requests.put(
    "https://api.alphacast.io/user-keys/fred",
    auth=("YOUR_API_KEY", ""),
    json={"api_key": "your-fred-api-key-here"},
)

# Remove the stored FRED API key
requests.put(
    "https://api.alphacast.io/user-keys/fred",
    auth=("YOUR_API_KEY", ""),
    json={"api_key": None},
)

// Save a FRED API key
await fetch("https://api.alphacast.io/user-keys/fred", {
  method: "PUT",
  headers: {
    Authorization: "Basic " + btoa("YOUR_API_KEY:"),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ api_key: "your-fred-api-key-here" }),
});

// Remove the stored FRED API key
await fetch("https://api.alphacast.io/user-keys/fred", {
  method: "PUT",
  headers: {
    Authorization: "Basic " + btoa("YOUR_API_KEY:"),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ api_key: null }),
});

Response fields

string

required

Provider slug that was updated.

boolean

required

true if a key is now stored, false if the key was removed.

Example response

{
  "slug": "fred",
  "has_key": true
}

After saving a key, all subsequent requests to GET /providers/fred/series/{series_id} and POST /providers/fred/series/{series_id}/data will automatically use it — you do not need to pass it explicitly in each request.

Overview

Repositories

Datasets

Data Providers

GET /providers — List and Browse Data Providers

Authentication

Endpoints

GET /providers

GET /providers/match

GET /providers/

GET /providers//browse

GET /providers//search

User API key management

GET /user-keys

PUT /user-keys/