Skills › Scientific Agent Skills › database-lookup › ecb.md

ecb.md

147 lines · skills/database-lookup/references/ecb.md at 5f2bc03

1# ECB Statistical Data Warehouse (SDW) REST API Reference

ECB Statistical Data Warehouse (SDW) REST API Reference

3## Overview

4The ECB SDW API provides access to European Central Bank statistical data: exchange rates, monetary aggregates, interest rates, balance of payments, banking statistics, and more. It follows the SDMX (Statistical Data and Metadata eXchange) RESTful web services standard.

Overview

The ECB SDW API provides access to European Central Bank statistical data: exchange rates, monetary aggregates, interest rates, balance of payments, banking statistics, and more. It follows the SDMX (Statistical Data and Metadata eXchange) RESTful web services standard.

Raw lines 3 to 5

6## Base URL

7```

8https://data-api.ecb.europa.eu/service

9```

11Use the current Data Portal host above; do not depend on the retired SDW hostname.

Base URL

https://data-api.ecb.europa.eu/service

Use the current Data Portal host above; do not depend on the retired SDW hostname.

Raw lines 6 to 12

13## Authentication

14**No API key required.** The API is fully open and public.

Authentication

No API key required. The API is fully open and public.

Raw lines 13 to 15

16## Rate Limits

17- No formal rate limits published.

18- ECB asks users to be respectful: avoid excessive parallel requests.

19- For bulk downloads, use compressed responses (`Accept-Encoding: gzip`).

Rate Limits

No formal rate limits published.
ECB asks users to be respectful: avoid excessive parallel requests.
For bulk downloads, use compressed responses (Accept-Encoding: gzip).

Raw lines 16 to 20

21## Formats

23Request `format=csvdata` for tabular output, `format=jsondata` for SDMX-JSON,

24`format=structurespecificdata` for SDMX-ML structure-specific data, or

25`format=genericdata` (default). Use `Accept-Encoding: gzip` for compression.

26The format contract is documented at https://data.ecb.europa.eu/help/api/data.

28---

Formats

Request format=csvdata for tabular output, format=jsondata for SDMX-JSON, format=structurespecificdata for SDMX-ML structure-specific data, or format=genericdata (default). Use Accept-Encoding: gzip for compression. The format contract is documented at https://data.ecb.europa.eu/help/api/data.

Raw lines 21 to 29

30## Key Endpoints

Key Endpoints

Raw lines 30 to 31

32### 1. Get Data (Time Series)

34```

35GET /data/{flowRef}/{key}?{parameters}

36```

38| Component | Description |

39|-----------|-------------|

40| `flowRef` | Dataflow ID (e.g., `EXR` for exchange rates, `BSI` for balance sheet items) |

41| `key` | Dot-separated dimension values. Use `+` for OR, `.` to skip a dimension (wildcard). |

43**Query Parameters:**

44| Parameter | Required | Description |

45|-----------|----------|-------------|

46| `startPeriod` | No | Start date: `YYYY`, `YYYY-MM`, or `YYYY-MM-DD` |

47| `endPeriod` | No | End date: same formats |

48| `updatedAfter` | No | ISO 8601 timestamp; returns only data updated after this time |

49| `detail` | No | `full` (default), `dataonly`, `serieskeysonly`, `nodata` |

50| `firstNObservations` | No | Return only first N observations per series |

51| `lastNObservations` | No | Return only last N observations per series |

52| `dimensionAtObservation` | No | Typically `TIME_PERIOD` (default) |

54**Exchange Rate Key Structure (EXR dataflow):**

55`{frequency}.{currency}.{currency_denom}.{exr_type}.{exr_suffix}`

57| Position | Dimension | Common Values |

58|----------|-----------|---------------|

59| 1 | Frequency | `D` (daily), `M` (monthly), `A` (annual) |

60| 2 | Currency | `USD`, `GBP`, `JPY`, `CHF`, `CNY`, etc. |

61| 3 | Currency denominator | `EUR` (usually) |

62| 4 | Exchange rate type | `SP00` (spot), `EN00` (average) |

63| 5 | Exchange rate suffix | `A` (average), `E` (end of period) |

65**Example -- Daily USD/EUR spot rate, 2024:**

66```

67GET https://data-api.ecb.europa.eu/service/data/EXR/D.USD.EUR.SP00.A?startPeriod=2024-01-01&endPeriod=2024-12-31

68Append `&format=jsondata` to the query URL.

69```

71**Example -- Monthly GBP and JPY vs EUR, last 12 observations:**

72```

73GET https://data-api.ecb.europa.eu/service/data/EXR/M.GBP+JPY.EUR.SP00.A?lastNObservations=12

74Append `&format=jsondata` to the query URL.

75```

77**Example -- All daily exchange rates for a specific date (wildcard):**

78```

79GET https://data-api.ecb.europa.eu/service/data/EXR/D..EUR.SP00.A?startPeriod=2024-06-01&endPeriod=2024-06-01

80Append `&format=jsondata` to the query URL.

81```

83**JSON parsing:** inspect the returned SDMX-JSON structure and use its dimension

84metadata to map index keys to series and dates. Do not assume a SDMX-JSON 2.0

85`data.structures` envelope. CSV (`format=csvdata`) is simpler for flat analyses;

86retain `TIME_PERIOD`, `OBS_VALUE`, unit and observation-status columns.

88---

1. Get Data (Time Series)

GET /data/{flowRef}/{key}?{parameters}

Component	Description
`flowRef`	Dataflow ID (e.g., `EXR` for exchange rates, `BSI` for balance sheet items)
`key`	Dot-separated dimension values. Use `+` for OR, `.` to skip a dimension (wildcard).

Query Parameters:

Parameter	Required	Description
`startPeriod`	No	Start date: `YYYY`, `YYYY-MM`, or `YYYY-MM-DD`
`endPeriod`	No	End date: same formats
`updatedAfter`	No	ISO 8601 timestamp; returns only data updated after this time
`detail`	No	`full` (default), `dataonly`, `serieskeysonly`, `nodata`
`firstNObservations`	No	Return only first N observations per series
`lastNObservations`	No	Return only last N observations per series
`dimensionAtObservation`	No	Typically `TIME_PERIOD` (default)

Exchange Rate Key Structure (EXR dataflow): {frequency}.{currency}.{currency_denom}.{exr_type}.{exr_suffix}

Position	Dimension	Common Values
1	Frequency	`D` (daily), `M` (monthly), `A` (annual)
2	Currency	`USD`, `GBP`, `JPY`, `CHF`, `CNY`, etc.
3	Currency denominator	`EUR` (usually)
4	Exchange rate type	`SP00` (spot), `EN00` (average)
5	Exchange rate suffix	`A` (average), `E` (end of period)

Example -- Daily USD/EUR spot rate, 2024:

GET https://data-api.ecb.europa.eu/service/data/EXR/D.USD.EUR.SP00.A?startPeriod=2024-01-01&endPeriod=2024-12-31
Append `&format=jsondata` to the query URL.

Example -- Monthly GBP and JPY vs EUR, last 12 observations:

GET https://data-api.ecb.europa.eu/service/data/EXR/M.GBP+JPY.EUR.SP00.A?lastNObservations=12
Append `&format=jsondata` to the query URL.

Example -- All daily exchange rates for a specific date (wildcard):

GET https://data-api.ecb.europa.eu/service/data/EXR/D..EUR.SP00.A?startPeriod=2024-06-01&endPeriod=2024-06-01
Append `&format=jsondata` to the query URL.

JSON parsing: inspect the returned SDMX-JSON structure and use its dimension metadata to map index keys to series and dates. Do not assume a SDMX-JSON 2.0 data.structures envelope. CSV (format=csvdata) is simpler for flat analyses; retain TIME_PERIOD, OBS_VALUE, unit and observation-status columns.

Raw lines 32 to 89

90### 2. Get Dataflow Definitions (Available Datasets)

92```

93GET /dataflow/{agencyID}/{resourceID}/{version}

94```

96**Example -- List all ECB dataflows:**

97```

98GET https://data-api.ecb.europa.eu/service/dataflow/ECB

99Accept: application/vnd.sdmx.structure+xml;version=2.1

100```

101

102**Example -- Get EXR dataflow definition:**

103```

104GET https://data-api.ecb.europa.eu/service/dataflow/ECB/EXR

105Accept: application/vnd.sdmx.structure+xml;version=2.1

106```

107

108---

109

2. Get Dataflow Definitions (Available Datasets)

GET /dataflow/{agencyID}/{resourceID}/{version}

Example -- List all ECB dataflows:

GET https://data-api.ecb.europa.eu/service/dataflow/ECB
Accept: application/vnd.sdmx.structure+xml;version=2.1

Example -- Get EXR dataflow definition:

GET https://data-api.ecb.europa.eu/service/dataflow/ECB/EXR
Accept: application/vnd.sdmx.structure+xml;version=2.1

Raw lines 90 to 109

110### 3. Get Data Structure Definition (Dimensions & Codes)

111

112```

113GET /datastructure/{agencyID}/{resourceID}/{version}?references=children

114```

115

116**Example:**

117```

118GET https://data-api.ecb.europa.eu/service/datastructure/ECB/ECB_EXR1?references=children

119Accept: application/vnd.sdmx.structure+xml;version=2.1

120```

121

122This returns all dimensions, their code lists, and allowed values -- essential for constructing valid keys.

123

124---

125

3. Get Data Structure Definition (Dimensions & Codes)

GET /datastructure/{agencyID}/{resourceID}/{version}?references=children

Example:

GET https://data-api.ecb.europa.eu/service/datastructure/ECB/ECB_EXR1?references=children
Accept: application/vnd.sdmx.structure+xml;version=2.1

This returns all dimensions, their code lists, and allowed values -- essential for constructing valid keys.

Raw lines 110 to 125

126## Common Dataflow IDs

127

128| Dataflow | Description |

129|----------|-------------|

130| `EXR` | Exchange rates |

131| `BSI` | Balance sheet items (monetary financial institutions) |

132| `MIR` | MFI interest rates |

133| `ILM` | Internal liquidity management |

134| `SEC` | Securities issues statistics |

135| `BOP` | Balance of payments |

136| `STP` | Structural financial indicators |

137| `CBD` | Consolidated banking data |

138| `ICP` | Index of consumer prices (HICP) |

139| `FM` | Financial market data |

140| `YC` | Yield curve data |

141

Common Dataflow IDs

Dataflow	Description
`EXR`	Exchange rates
`BSI`	Balance sheet items (monetary financial institutions)
`MIR`	MFI interest rates
`ILM`	Internal liquidity management
`SEC`	Securities issues statistics
`BOP`	Balance of payments
`STP`	Structural financial indicators
`CBD`	Consolidated banking data
`ICP`	Index of consumer prices (HICP)
`FM`	Financial market data
`YC`	Yield curve data

Raw lines 126 to 141

142## Notes

143- The SDMX-JSON format is verbose. For simpler parsing, use `format=csvdata`.

144- When a dimension is unknown, leave it empty (e.g., `D..EUR.SP00.A`) to get all values for that dimension.

145- Use `+` to request multiple values for one dimension (e.g., `USD+GBP`).

146- The `detail=dataonly` parameter omits attributes and reduces response size.

147- Historical data availability varies by dataflow; exchange rates go back to 1999 (euro introduction).

Notes

The SDMX-JSON format is verbose. For simpler parsing, use format=csvdata.
When a dimension is unknown, leave it empty (e.g., D..EUR.SP00.A) to get all values for that dimension.
Use + to request multiple values for one dimension (e.g., USD+GBP).
The detail=dataonly parameter omits attributes and reduces response size.
Historical data availability varies by dataflow; exchange rates go back to 1999 (euro introduction).

Raw lines 142 to 147