> ## Documentation Index
> Fetch the complete documentation index at: https://alphacastio.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect to External Data Providers

> Pull series from central banks, statistical agencies, market data sources, and international organizations through a single unified Alphacast API. Browse the live catalog at alphacast.io/explore/apis.

Alphacast connects you to a curated catalog of 30+ external data providers — central banks, national statistics offices, market data sources, and international organizations — through a single unified interface. Every provider follows the same REST conventions: browse, search, preview, then fetch. You do not need to learn each provider's native API.

<Card title="Browse the live catalog →" icon="compass" href="https://www.alphacast.io/explore/apis">
  The authoritative list of providers, their capabilities, popular series, and any API-key requirements lives at **alphacast.io/explore/apis**. That page is always the source of truth — this documentation only describes how to use the API surface.
</Card>

## Currently supported providers

The catalog is grouped below by provider type. All slugs are case-insensitive — `FRED`, `fred`, and `Fred` resolve to the same provider. Use them in the API paths described later on this page.

### Central banks

| Slug         | Provider                                       | API key  |
| ------------ | ---------------------------------------------- | -------- |
| `banrep`     | Banco de la República (Colombia)               | —        |
| `banxico`    | Banxico — Banco de México                      | Required |
| `bcch`       | Banco Central de Chile (BDE)                   | Required |
| `bcra`       | BCRA — Banco Central de la República Argentina | —        |
| `bcrp`       | BCRP — Banco Central de Reserva del Perú       | —        |
| `boc`        | Bank of Canada (Valet)                         | —        |
| `boe`        | Bank of England                                | —        |
| `boi`        | Bank of Israel                                 | —        |
| `ecb`        | European Central Bank                          | —        |
| `hkma`       | Hong Kong Monetary Authority                   | —        |
| `norges`     | Norges Bank                                    | —        |
| `taiwan-cbc` | Central Bank of Taiwan (CBC DataAPI)           | —        |

### National statistics offices

| Slug       | Provider                                                       | API key  |
| ---------- | -------------------------------------------------------------- | -------- |
| `abs`      | Australian Bureau of Statistics                                | —        |
| `bls`      | U.S. Bureau of Labor Statistics                                | Optional |
| `eurostat` | Eurostat                                                       | —        |
| `faostat`  | FAO FAOSTAT                                                    | —        |
| `inegi`    | INEGI — Instituto Nacional de Estadística y Geografía (Mexico) | Required |
| `insee`    | INSEE (France)                                                 | —        |
| `oecd`     | OECD Statistics                                                | —        |
| `opendosm` | OpenDOSM (Malaysia)                                            | —        |
| `scb`      | Statistics Sweden                                              | —        |
| `sidra`    | IBGE SIDRA (Brazil)                                            | —        |
| `ssb`      | Statistics Norway                                              | —        |
| `unsd`     | UN Statistics Division                                         | —        |

### Markets and finance

| Slug           | Provider                                      | API key  |
| -------------- | --------------------------------------------- | -------- |
| `a3`           | A3 Mercados (Matba/Rofex, Argentina)          | —        |
| `bcb-opendata` | BCB — Banco Central do Brasil (Open Data)     | —        |
| `bis`          | BIS — Bank for International Settlements      | —        |
| `coingecko`    | CoinGecko                                     | Optional |
| `mae`          | MAE — Mercado Abierto Electrónico (Argentina) | —        |

### U.S. federal agencies

| Slug   | Provider                                      | API key  |
| ------ | --------------------------------------------- | -------- |
| `bea`  | U.S. Bureau of Economic Analysis              | Required |
| `eia`  | U.S. Energy Information Administration        | Required |
| `fred` | Federal Reserve Economic Data (St. Louis Fed) | Required |

### International organizations

| Slug        | Provider                          | API key |
| ----------- | --------------------------------- | ------- |
| `ilo`       | International Labour Organization | —       |
| `imf`       | International Monetary Fund       | —       |
| `unicef`    | UNICEF Data Warehouse             | —       |
| `worldbank` | World Bank Open Data              | —       |

### Curated and other

| Slug        | Provider          | API key |
| ----------- | ----------------- | ------- |
| `cepalstat` | CEPALSTAT (ECLAC) | —       |
| `owid`      | Our World in Data | —       |

To see capabilities (`hierarchical`, `search`, `direct`), parameters, and popular series for any provider, call `GET /providers/{slug}` or open it in [the live catalog](https://www.alphacast.io/explore/apis).

## API endpoints

All provider endpoints are available under `https://api.alphacast.io`. Authentication uses your Alphacast API key over HTTP Basic Auth — see the [authentication guide](/authentication).

### List and discover providers

```bash theme={null}
# List all enabled providers with their slugs, capabilities, and license
GET /providers

# Get full detail for a single provider: capabilities, parameters, popular series
GET /providers/{slug}
```

### Browse, search, and fetch series

```bash theme={null}
# Browse hierarchically (topics, categories, surveys)
GET /providers/{slug}/browse?path=

# Full-text search for series within a provider
GET /providers/{slug}/search?q={query}

# Preview the last 24 data points for a series
GET /providers/{slug}/series/{series_id}

# Fetch the full series history
POST /providers/{slug}/series/{series_id}/data
```

### Manage your API keys

```bash theme={null}
# List which providers you have API keys stored for
GET /user-keys

# Save (or update) your API key for a provider
PUT /user-keys/{slug}
```

<Info>
  For providers that require a key (FRED, BLS, INEGI, Banxico, BEA, EIA, BCCH), save your key once using `PUT /user-keys/{slug}`. Alphacast stores it securely and passes it automatically on every subsequent request. You never need to include it in individual calls.
</Info>

## Capability types

Each provider declares which access patterns it supports.

| Capability     | Description                                                        |
| -------------- | ------------------------------------------------------------------ |
| `hierarchical` | Browse a tree of topics, categories, or surveys to discover series |
| `search`       | Full-text search for series by name or keyword                     |
| `direct`       | Fetch a series directly if you already know its ID                 |

You can check a provider's capabilities with `GET /providers/{slug}` before deciding how to query it.

## Complete example: list, search, and fetch

The walkthrough below shows the full flow from discovering providers to downloading data.

<Steps>
  <Step title="List all providers">
    Retrieve the catalog to see slugs and capabilities.

    ```bash theme={null}
    curl https://api.alphacast.io/providers
    ```

    Each entry in the response includes `slug`, `name`, `capabilities`, and `license`.
  </Step>

  <Step title="Inspect a provider">
    Fetch provider detail including its parameters and popular series IDs.

    ```bash theme={null}
    curl https://api.alphacast.io/providers/fred
    ```

    The response includes `popular_series` (a list of well-known series IDs), `parameters` (optional request modifiers), and `browse_root_label`.
  </Step>

  <Step title="Search for a series">
    Find a series by keyword. Only providers with the `search` capability support this endpoint.

    ```bash theme={null}
    curl "https://api.alphacast.io/providers/fred/search?q=consumer+price+index"
    ```

    Each result contains `series_id` and `label`. Use the `series_id` in the next step.
  </Step>

  <Step title="Preview the series">
    Retrieve the last 24 data points to confirm you have the right series.

    ```bash theme={null}
    curl https://api.alphacast.io/providers/fred/series/CPIAUCSL
    ```

    The response includes `label`, `metadata` (frequency, units, date range), and a `data` array limited to 24 observations. The `is_preview: true` field indicates this is a truncated response.
  </Step>

  <Step title="Fetch the full series">
    Issue a POST to retrieve all historical data. Pass optional parameters in the request body.

    <CodeGroup>
      ```bash Full history theme={null}
      curl -X POST https://api.alphacast.io/providers/fred/series/CPIAUCSL/data \
        -H "Content-Type: application/json" \
        -d '{}'
      ```

      ```bash With parameters theme={null}
      curl -X POST https://api.alphacast.io/providers/fred/series/CPIAUCSL/data \
        -H "Content-Type: application/json" \
        -d '{"params": {"units": "pc1", "frequency": "m"}}'
      ```
    </CodeGroup>

    The response contains the same structure as the preview but with `is_preview: false` and the full `data` array.
  </Step>

  <Step title="Save an API key (if required)">
    For providers like FRED, BLS, INEGI, or Banxico that enforce rate limits or require authentication, save your key once.

    ```bash theme={null}
    curl -X PUT https://api.alphacast.io/user-keys/fred \
      -H "Content-Type: application/json" \
      -d '{"api_key": "your_fred_api_key_here"}'
    ```

    After saving, Alphacast uses your key automatically on all subsequent requests to that provider.
  </Step>
</Steps>

<Tip>
  Not sure which provider has the data you need? Use the provider match endpoint with a free-text description: `GET /providers/match?q=argentina+exchange+rate`. It returns the top matching providers based on your query.
</Tip>