Fetch Series Data from External Providers

Preview or download complete time-series data from FRED, BLS, World Bank, OECD, IMF, BIS, ECB, Eurostat, and central banks across Latin America, Europe, and Asia using the Alphacast provider API.

Once you have found a series ID — through browsing, searching, or the popular series list — you can fetch its data in two steps: a lightweight preview that returns the most recent data points, followed by a full historical fetch. For FRED series, a dedicated shortcut endpoint is also available that bypasses the provider slug workflow.

Authentication

All 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/fred/series/UNRATE

For providers that require an upstream API key (such as FRED or INEGI), save your key via PUT /user-keys/{slug} first. Alphacast applies it automatically on every series request.

---

Provider series endpoints

GET /providers//series/

Returns a preview of the series: the last ~24 data points, the series label, and metadata. The response always includes "is_preview": true to signal that the data is truncated.

Use this endpoint to confirm you have the right series before fetching the full history.

Path parameters

slug · string · required

Provider slug. Examples: fred, bls, worldbank, bcra, banxico.

series_id · string · required

The series identifier as recognized by the upstream provider. Format varies by provider — for example, UNRATE for FRED, CUUR0000SA0 for BLS, or NY.GDP.PCAP.CD for World Bank.

Some providers — notably SDMX-style sources (UNICEF, ECB, INSEE, BOI, FAOSTAT, Norges Bank) — use hierarchical IDs that contain forward slashes, such as IMF/IFS/Q.US.NGDP_XDC. Alphacast accepts these in the URL as-is; you do not need to URL-encode the / characters.

cURL

# Flat ID
curl -u YOUR_API_KEY: \
  https://api.alphacast.io/providers/fred/series/UNRATE

# Hierarchical SDMX-style ID with slashes — passed through verbatim
curl -u YOUR_API_KEY: \
  https://api.alphacast.io/providers/ecb/series/EXR/D.USD.EUR.SP00.A

import requests

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

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

Response fields

series_id · string · required

The series identifier that was requested.

label · string · required

Descriptive name of the series as provided by the upstream source. Example: "Unemployment Rate".

metadata · object · required

Provider-specific metadata about the series. Contents vary by provider but may include frequency, units, seasonal adjustment, source, and notes.

data · object[] · required

Array of data points, most recent ~24 observations. Each item has:

Show data point properties

date · string

Observation date in YYYY-MM-DD format.

value · number | null

Numeric value for the observation. null when the upstream source reports a missing value.

is_preview · boolean · required

Always true for this endpoint. Indicates the data array is truncated to the most recent observations.

api_key_required · boolean

Present when the provider requires an upstream API key. Always true in that case.

has_api_key · boolean

Present when api_key_required is true. Whether you have a stored key for this provider.

api_key_hint · string

Present when api_key_required is true. Instructions for obtaining and saving an API key.

Example response

{
  "series_id": "UNRATE",
  "label": "Unemployment Rate",
  "metadata": {
    "frequency": "Monthly",
    "units": "Percent",
    "seasonal_adjustment": "Seasonally Adjusted",
    "last_updated": "2024-04-05"
  },
  "data": [
    {"date": "2024-03-01", "value": 3.8},
    {"date": "2024-02-01", "value": 3.9},
    {"date": "2024-01-01", "value": 3.7},
    {"date": "2023-12-01", "value": 3.7}
  ],
  "is_preview": true
}

Handling api_key_required

When a provider needs an upstream key and you have not stored one, the preview still returns recent data where possible, but includes the key status fields:

{
  "series_id": "GDP",
  "label": "Gross Domestic Product",
  "metadata": {"frequency": "Quarterly", "units": "Billions of Dollars"},
  "data": [{"date": "2024-01-01", "value": 27360.9}],
  "is_preview": true,
  "api_key_required": true,
  "has_api_key": false,
  "api_key_hint": "A FRED API key is required. Get one for free."
}

Store your key with PUT /user-keys/fred to remove the restriction.

---

POST /providers//series//data

Returns the full historical time series. This endpoint accepts provider-specific parameters in the request body to control units, frequency, date ranges, and other transformations.

Path parameters

slug · string · required

Provider slug.

series_id · string · required

Series identifier.

Request body

params · object · default: "{}"

Provider-specific parameters. The available keys depend on the provider — consult the parameters array in GET /providers/{slug} for valid options.

Common examples:

Provider	Parameter key	Example value
FRED	units	"pc1" (% change from year ago)
FRED	frequency	"q" (quarterly)
BLS	startyear	2010
BLS	endyear	2024
World Bank	country	"BR"
World Bank	date_range	"2000:2024"

cURL

# Fetch full FRED unemployment data, resampled to annual % change
curl -u YOUR_API_KEY: \
  -X POST https://api.alphacast.io/providers/fred/series/UNRATE/data \
  -H "Content-Type: application/json" \
  -d '{"params": {"units": "pc1", "frequency": "a"}}'

import requests

response = requests.post(
    "https://api.alphacast.io/providers/fred/series/UNRATE/data",
    auth=("YOUR_API_KEY", ""),
    json={"params": {"units": "pc1", "frequency": "a"}},
)
series = response.json()

const response = await fetch(
  "https://api.alphacast.io/providers/fred/series/UNRATE/data",
  {
    method: "POST",
    headers: {
      Authorization: "Basic " + btoa("YOUR_API_KEY:"),
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ params: { units: "pc1", frequency: "a" } }),
  },
);
const series = await response.json();

Response fields

The response has the same structure as the preview endpoint, with one difference:

is_preview · boolean · required

Always false. The data array contains the complete historical series.

series_id · string · required

The requested series ID.

label · string · required

Descriptive name of the series.

metadata · object · required

Provider-specific metadata.

data · object[] · required

Complete array of all available observations, each with date (string, YYYY-MM-DD) and value (number or null).

Example response

{
  "series_id": "UNRATE",
  "label": "Unemployment Rate",
  "metadata": {
    "frequency": "Monthly",
    "units": "Percent",
    "seasonal_adjustment": "Seasonally Adjusted",
    "last_updated": "2024-04-05"
  },
  "data": [
    {"date": "1948-01-01", "value": 3.4},
    {"date": "1948-02-01", "value": 3.8},
    "...",
    {"date": "2024-03-01", "value": 3.8}
  ],
  "is_preview": false
}

---

Complete workflow example

The following example shows the full sequence: match a provider, search for a series, preview it, then fetch the complete history.

1. Find the right provider

   curl -u YOUR_API_KEY: \
     "https://api.alphacast.io/providers/match?q=federal+reserve+interest+rates"
   
2. Search for a series within the provider

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

   Note the id from the results — for example, FEDFUNDS.

3. Preview the series

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

   Check that label and metadata match what you expect. Confirm is_preview: true.

4. Fetch the full history

   curl -u YOUR_API_KEY: \
     -X POST https://api.alphacast.io/providers/fred/series/FEDFUNDS/data \
     -H "Content-Type: application/json" \
     -d '{"params": {"frequency": "m"}}'
   

   The response contains the complete monthly series with is_preview: false.

---

FRED direct endpoints

These endpoints provide a streamlined interface to FRED without the provider slug workflow. They are useful when you already know your FRED symbol.

GET /fred/search/

Searches FRED for series matching the query string and returns matching symbols and descriptions.

Path parameters

query · string · required

Search term to look up in FRED. URL-encode spaces as %20 or +.

curl -u YOUR_API_KEY: \
  "https://api.alphacast.io/fred/search/consumer+price+index"

Response

{
  "results": [
    {
      "id": "CPIAUCSL",
      "title": "Consumer Price Index for All Urban Consumers: All Items in U.S. City Average",
      "frequency": "Monthly",
      "units": "Index 1982-1984=100"
    }
  ]
}

---

GET /fred//data

Fetches time-series data for a FRED symbol directly. Returns data as CSV by default; use $format=json for a JSON response.

Path parameters

symbol · string · required

FRED series symbol. Examples: GDP, UNRATE, CPIAUCSL, FEDFUNDS, DGS10.

Query parameters

$format · string · default: "csv"

Output format. Accepted values: json, csv, xlsx, tsv.

$top · number

Limit the number of rows returned. Omit to return all available data.

start · string

Start date filter in YYYY-MM-DD format.

end · string

End date filter in YYYY-MM-DD format.

# Get CPIAUCSL as JSON, last 5 rows
curl -u YOUR_API_KEY: \
  "https://api.alphacast.io/fred/CPIAUCSL/data?$format=json&$top=5"

# Get data between two dates
curl -u YOUR_API_KEY: \
  "https://api.alphacast.io/fred/GDP/data?$format=json&start=2020-01-01&end=2023-12-31"

---

Error responses

All endpoints return a JSON error object with an error field when a request fails.

Status	Meaning
400	The provider does not support the requested operation (e.g., browse on a non-hierarchical provider).
404	Provider slug or series ID not found.
501	The connector does not implement this operation.
502	The upstream provider returned an error. Check the error message for details.

{
  "error": "Provider does not support hierarchical browse"
}