Fetch Series Data from External Providers

# 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();

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

string

required

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

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.

# 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

string

required

The series identifier that was requested.

string

required

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

object

required

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

object[]

required

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

Show data point properties

string

Observation date in YYYY-MM-DD format.

number | null

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

boolean

required

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

boolean

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

boolean

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

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

string

required

Provider slug.

string

required

Series identifier.

Request body

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"`

# 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:

boolean

required

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

string

required

The requested series ID.

string

required

Descriptive name of the series.

object

required

Provider-specific metadata.

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.

Find the right provider

curl -u YOUR_API_KEY: \
  "https://api.alphacast.io/providers/match?q=federal+reserve+interest+rates"

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.

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.

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

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

string

required

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

Query parameters

string

default:"csv"

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

number

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

string

Start date filter in YYYY-MM-DD format.

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"
}

# 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();

Overview

Repositories

Datasets

Data Providers

Fetch Series Data from External Providers

Authentication

Provider series endpoints

GET /providers//series/

POST /providers//series//data

Complete workflow example

FRED direct endpoints

GET /fred/search/

GET /fred//data

Error responses