Skip to main content
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

​
GET /providers

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
Response fields
​
slug
string
required
Unique identifier for the provider. Use this as the {slug} path parameter in all other provider endpoints. Examples: fred, bls, worldbank, bcra.
​
name
string
required
Human-readable name of the data collection. Examples: FRED Economic Data, BLS Public Data.
​
provider
string
required
Name of the organization that publishes the data. Examples: Federal Reserve Bank of St. Louis, U.S. Bureau of Labor Statistics.
​
description
string
required
Short description of what the provider covers — topics, geography, and data types.
​
capabilities
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
​
license
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
​
q
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:
​
parameters
object[]
List of configurable parameters for the provider (same structure as in provider detail).
​
popular_series
object[]
Curated list of commonly used series IDs and labels for this provider.
​
api_key_required
boolean
Present and true when the provider requires you to supply your own API key from the upstream source.
​
has_api_key
boolean
Present when api_key_required is true. Indicates whether you have already saved an API key for this provider via /user-keys/{slug}.
​
api_key_label
string
Human-readable label for the key field, such as "FRED API Key" or "INEGI API Token".
​
api_key_hint
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
​
slug
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
​
slug
string
required
Provider slug.
​
name
string
required
Display name.
​
provider
string
required
Publishing organization name.
​
description
string
required
Description of the data covered.
​
capabilities
string[]
required
Supported operations: "hierarchical", "search", "direct".
​
parameters
object[]
Provider-specific parameters you can pass when fetching series data. Each parameter object includes:
​
popular_series
object[]
Curated series suggestions. Each item has id (the series ID) and label (a descriptive name).
​
license
string
Data license.
​
api_key_url
string
URL where you can register for an API key with the upstream provider, if applicable.
​
api_key_label
string
Label for the API key field.
​
anonymous_limit_message
string
Message describing rate limits or access restrictions without a key.
​
browse_root_label
string
Display name for the root level of the provider’s category tree. Example: "Categories" for FRED, "Topics" for World Bank.
​
series_id_placeholder
string
Example series ID format for this provider. Example: "e.g. GDP, UNRATE, CPIAUCSL" for FRED.
​
has_user_api_key
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
​
slug
string
required
Provider slug.
Query parameters
​
path
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".
​
depth
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.
​
series
boolean
When true, returns paginated series at the current path instead of sub-folders.
​
limit
number
default:"200"
Page size when series=true. Maximum is 1000.
​
offset
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
​
slug
string
required
Provider slug.
Query parameters
​
q
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
​
query
string
required
The search query that was submitted.
​
items
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
​
slug
string
required
Provider slug. Must match an existing provider in the catalog.
Request body
​
api_key
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}'
Response fields
​
slug
string
required
Provider slug that was updated.
​
has_key
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.