Integration Prompt

# Integrate EconomicsAPI into my application

You are integrating EconomicsAPI into my application end-to-end. Economics and trade data your AI can use. It is a plain REST API over HTTPS (JSON in, JSON out), no SDK required. Base URL: `https://api.economicsapi.com`. Full reference: https://docs.economicsapi.com/api-reference · https://docs.economicsapi.com/openapi.json (OpenAPI).

## My application context

<my_stack>
Stack: [framework + language: e.g. Next.js + TypeScript, Django, Rails, Go]
Surface: [web | mobile | backend-only | agent/automation]
Use case: [what I want to do with this API, in one line]
Database: [Postgres | MySQL | Mongo | none]
</my_stack>

## Step 1: Get an API key

1. Sign up at https://app.economicsapi.com/signup and create an API key in the dashboard (it is shown once: store it as the env var `ECONOMICSAPI_API_KEY`).
2. Never ship the key to a browser or mobile app: call the API from my backend only.

## Step 2: Authentication and conventions

- Every request sends `Authorization: Bearer $API_KEY`. Missing/invalid → `401 invalid_key`.
- Send/receive JSON: `Content-Type: application/json`.
- Every response carries `x-request-id` (also `request_id` in the body). Log it with every call.
- `429` → honor `Retry-After`, then retry with exponential backoff (max 3). `503`/`504` → retry with backoff. `4xx` other than 429 → do not retry, fix the request.
- The free plan includes 100 API calls per account; Pro is unlimited. The dashboard shows plan and usage.

## Step 3: Endpoints

### economics: GDP, prices, labour, money, government and external-sector indicators for 50 countries

- `GET /v1/economics/available`: Available economics. Countries and indicator names you can use with latest, history and forecasts.. params: { country: string, q?: string | null, view?: enum, limit?: integer, offset?: integer }. returns: { data: { countries: CountryOut[], indicators: IndicatorOut[], next_offset?: integer | null } }. errors: 401/422/429.
- `GET /v1/countries`: Countries. returns: { data: { country_id: string, name: string, slug: string, iso2?: string | null, kind: string, groups?: string[] }[] }. errors: 401/429.
- `GET /v1/indicators`: Indicators. Start here.. params: { country?: string | null, q?: string | null, view?: enum }. returns: { data: { kpi_id: string, slug: string, name: string, group: string, unit: string, unit_code: string, frequency: string, description?: string | null, aliases?: string[] }[] }. errors: 401/422/429.
- `GET /v1/resolve`: Data availability. params: { country?: string | null, indicator?: string | null, group?: string | null, include_series?: boolean }. returns: { data: { countries: CountryOut[], indicators: IndicatorOut[], series: SeriesAvailability[] } }. errors: 401/422/429.
- `GET /v1/latest`: Latest indicators. Use country=mexico&indicator=inflation or indicator=unemployment.. params: { country?: string | null, indicator?: string | null, group?: string | null }. returns: { data: { series_id: string, country_id: string, country: string, kpi_id: string, indicator: string, slug: string, group: string, latest_value: number, latest_value_date: string<date>, previous_value?: number | null, previous_value_date?: string<date> | null, highest_value?: number | null, highest_value_date?: string<date> | null, lowest_value?: number | null, lowest_value_date?: string<date> | null, unit: string, unit_code: string, value_type: string, comparison_basis?: string | null, price_basis?: string | null, interpretation: string, frequency: string, adjustment?: string | null, observation_status: string, observation_status_code?: string | null, source_id: string, source_series_id: string, source_name: string, source_url: string, license_id: string, attribution_text: string, first_value_date?: string<date> | null, last_value_date?: string<date> | null, observation_count?: integer, last_update?: string<date-time> | null }[], retrieved_at: string<date-time>, reproduction_url: string }. errors: 401/422/429.
- `GET /v1/history`: Indicator history. Use the same country and indicator as /v1/latest, with optional from/to years or dates.. params: { country?: string | null, indicator?: string | null, from?: string | null, to?: string | null, transform?: string, cursor?: string | null }. returns: { data: { series_id: string, country_id: string, kpi_id: string, date: string<date>, value: number, frequency: string, obs_status?: string, observation_status: string, unit: string, unit_code: string, value_type: string, comparison_basis?: string | null, price_basis?: string | null, interpretation: string, adjustment?: string | null, source_id: string, source_series_id: string, source_name: string, source_url: string, license_id: string, attribution_text: string, coverage_start?: string<date> | null, coverage_end?: string<date> | null, coverage_observation_count?: integer, is_derived?: boolean, transformation?: string, transformation_formula?: string | null, last_update?: string<date-time> | null }[], next_cursor?: string | null, retrieved_at: string<date-time>, reproduction_url: string }. errors: 401/422/429.
- `GET /v1/search`: Search indicators. params: { q: string, limit?: integer }. returns: { data: { type: string, title: string, series_id?: string | null, country_id?: string | null, kpi_id?: string | null, slug?: string | null, latest_value?: number | null, latest_value_date?: string<date> | null, unit?: string | null, frequency?: string | null }[] }. errors: 401/422/429.
- `GET /v1/updates`: Data updates. params: { since: string, country?: string | null }. returns: { data: { series_id: string, country_id: string, kpi_id: string, slug: string, last_update: string<date-time> }[] }. errors: 401/422/429.
- `GET /v1/news`: Economic news. params: { country?: string | null, indicator?: string | null, kind?: string | null, min_importance?: integer | null, since?: string | null, before?: string | null, limit?: integer, slug?: string | null }. returns: { data: { slug: string, kind: string, importance: integer, headline: string, body: string, country: string, indicator: string, obs_date: string<date>, published_at: string<date-time>, source_name: string }[] }. errors: 401/422/429.
- `GET /v1/forecast`: Indicator forecasts. Predicted indicator values by date.. params: { country?: string | null, indicator?: string | null, group?: string | null, horizon?: integer | null }. returns: { data: { country_id: string, country: string, indicator: string, slug: string, frequency: string, unit: string, forecast: ForecastPoint[] }[] }. errors: 401/422/429.

### trade: Bilateral goods trade for 41 countries, 2015 to today

- `GET /v1/trade/available`: Available trade. Country names, product codes and flow directions accepted by trade requests.. params: { q?: string | null, country?: string | null, limit?: integer, offset?: integer }. returns: { data: { countries: CountryRow[], products: ProductRow[], flows: string[], next_offset?: integer | null }, request_id?: string, duration_ms?: integer }. errors: 401/422/429.
- `GET /v1/trade`: Trade flows. Individual exporter→importer→product→year flows, filtered by reporter, partner, product, flow direction and period.. params: { reporter?: string | null, partner?: string | null, product?: string | null, flow?: string | null, from?: string | null, to?: string | null, limit?: integer }. returns: { data: { exporter: string, importer: string, hs6: string, hs_version: integer, period: string<date>, granularity: string, value_usd: number, quantity: number | null, quantity_unit: string }[], request_id?: string, duration_ms?: integer }. errors: 401/422/429.
- `GET /v1/trade/summary`: Trade summary. Total value, quantity, growth, unit value, top partners and partner concentration (HHI) for any reporter/partner/product/period selection.. params: { reporter?: string | null, partner?: string | null, product?: string | null, flow?: string | null, from?: string | null, to?: string | null }. returns: { data: { trade_value: number | null, quantity: number | null, growth: number | null, unit_value: number | null, top_partners: TopPartner[], partner_concentration: number | null, periods: PeriodPoint[] }, request_id?: string, duration_ms?: integer }. errors: 401/422/429.
- `GET /v1/trade/monthly`: Monthly trade. Monthly bilateral flows, one value per exporter, importer, product and month.. params: { exporter?: string | null, importer?: string | null, product?: string | null, from?: string | null, to?: string | null, method?: string | null, group_by?: string | null, limit?: integer }. returns: { data: MonthlyObservation[] | MonthlyGroupedPoint[], request_id?: string, duration_ms?: integer }. errors: 401/422/429.
- `GET /v1/trade/coverage`: Trade coverage. Canonical ISO codes, availability, and yearly/monthly spans.. params: { country?: string | null }. returns: { data: { country: string, iso3?: string | null, name: string, trade_available: boolean, yearly_first: integer | null, yearly_last: integer | null, monthly_first: string<date> | null, monthly_last: string<date> | null }[], request_id?: string, duration_ms?: integer }. errors: 401/422/429.
- `GET /v1/trade/products`: Trade products. Search the HS6 product catalog by code prefix or name.. params: { q: string, limit?: integer }. returns: { data: { hs6: string, hs_version: integer, name: string }[], request_id?: string, duration_ms?: integer }. errors: 401/422/429.
- `GET /v1/trade/products/{pid}`: Product details. Metadata for an HS6 code ('390210', 'hs:390210') or a 2-4 digit chapter prefix.. params: { pid: string }. returns: { data: { id: string, matches: ProductMatch[] }, request_id?: string, duration_ms?: integer }. errors: 401/422/429.
- `GET /v1/trade/products/{pid}/history`: Product history. Annual trade series for one product, optionally filtered by reporter/partner and flow direction.. params: { pid: string, reporter?: string | null, partner?: string | null, flow?: string | null, from?: string | null, to?: string | null }. returns: { data: { period?: string<date> | null, partner?: string | null, exporter?: string | null, importer?: string | null, hs6?: string | null, value_usd: number, quantity: number | null, flow_count: integer }[], request_id?: string, duration_ms?: integer }. errors: 401/422/429.
- `GET /v1/trade/products/{pid}/markets`: Product trading partners. Top exporting and importing countries for a product over a period.. params: { pid: string, from?: string | null, to?: string | null, limit?: integer }. returns: { data: { top_exporters: GroupedPoint[], top_importers: GroupedPoint[] }, request_id?: string, duration_ms?: integer }. errors: 401/422/429.
- `GET /v1/trade/countries`: Trade countries. Resolve a country name, ISO alpha-2 or alpha-3 code.. params: { q: string, limit?: integer }. returns: { data: { id: string, iso3?: string | null, name: string, is_group: boolean, trade_available: boolean }[], request_id?: string, duration_ms?: integer }. errors: 401/422/429.
- `GET /v1/trade/countries/{cid}`: Country details. Country metadata and trade availability (id = ISO alpha-2).. params: { cid: string }. returns: { data: { id: string, iso3?: string | null, name: string, is_group: boolean, trade_available: boolean, region?: string | null, note?: string | null }, request_id?: string, duration_ms?: integer }. errors: 401/422/429.
- `GET /v1/trade/countries/{cid}/imports`: Country imports. Annual import value/quantity series for one country, optionally filtered by partner and product.. params: { cid: string, partner?: string | null, product?: string | null, from?: string | null, to?: string | null }. returns: { data: { period?: string<date> | null, partner?: string | null, exporter?: string | null, importer?: string | null, hs6?: string | null, value_usd: number, quantity: number | null, flow_count: integer }[], request_id?: string, duration_ms?: integer }. errors: 401/422/429.
- `GET /v1/trade/countries/{cid}/exports`: Country exports. Annual export value/quantity series for one country, optionally filtered by partner and product.. params: { cid: string, partner?: string | null, product?: string | null, from?: string | null, to?: string | null }. returns: { data: { period?: string<date> | null, partner?: string | null, exporter?: string | null, importer?: string | null, hs6?: string | null, value_usd: number, quantity: number | null, flow_count: integer }[], request_id?: string, duration_ms?: integer }. errors: 401/422/429.
- `GET /v1/trade/countries/{cid}/partners`: Country partners. A country's partners ranked by trade value, for either flow direction, optionally per product.. params: { cid: string, flow?: string | null, product?: string | null, from?: string | null, to?: string | null, limit?: integer }. returns: { data: { period?: string<date> | null, partner?: string | null, exporter?: string | null, importer?: string | null, hs6?: string | null, value_usd: number, quantity: number | null, flow_count: integer }[], request_id?: string, duration_ms?: integer }. errors: 401/422/429.
- `GET /v1/trade/countries/{cid}/products`: Country products. What a country trades, grouped by HS6 product and ranked by value, for either flow direction.. params: { cid: string, flow?: string | null, from?: string | null, to?: string | null, limit?: integer }. returns: { data: { period?: string<date> | null, partner?: string | null, exporter?: string | null, importer?: string | null, hs6?: string | null, value_usd: number, quantity: number | null, flow_count: integer }[], request_id?: string, duration_ms?: integer }. errors: 401/422/429.

### fx: Currency pairs: official reference exchange rates

- `GET /v1/fx/available`: Available fx rates. Find names for foreign exchange reference rates with q.. params: { q: string, limit?: integer, offset?: integer }. returns: { data: { slug: string, name: string, aliases: string[], category: string, currency: string, unit: string, frequency: string }[], next_offset?: integer | null }. errors: 401/422/429.
- `GET /v1/fx/{slug}/history`: FX rates history. Dated source observations, oldest first.. params: { slug: string, from?: string<date> | null, to?: string<date> | null, limit?: integer }. returns: { data: { observed_on: string<date>, value: string }[] }. errors: 401/422/429.
- `GET /v1/fx/{slug}`: Latest FX rate. Use a slug returned by getFxAvailable.. params: { slug: string }. returns: { data: { aliases?: string[], instrument_id: string, slug: string, category: string, name: string, description: string, geography?: string | null, venue?: string | null, currency: string, unit: string, price_type: string, frequency: string, source_id: string, source_name: string, source_url: string, attribution: string, value: string, observed_on: string<date>, previous_value?: string | null, previous_observed_on?: string<date> | null, high_value?: string | null, high_observed_on?: string<date> | null, low_value?: string | null, low_observed_on?: string<date> | null, fetched_at?: string<date-time> | null, last_checked?: string<date-time> | null, stale: boolean, observation_count: integer } }. errors: 401/422/429.

### commodities: Energy, metals, industrial materials and electricity benchmarks

- `GET /v1/commodities/available`: Available commodity prices. Find names for commodity prices with q.. params: { q: string, limit?: integer, offset?: integer }. returns: { data: { slug: string, name: string, aliases: string[], category: string, currency: string, unit: string, frequency: string }[], next_offset?: integer | null }. errors: 401/422/429.
- `GET /v1/commodities/{slug}/history`: Commodity prices history. Dated source observations, oldest first.. params: { slug: string, from?: string<date> | null, to?: string<date> | null, limit?: integer }. returns: { data: { observed_on: string<date>, value: string }[] }. errors: 401/422/429.
- `GET /v1/commodities/{slug}`: Latest commodity price. Use a slug returned by getCommoditiesAvailable.. params: { slug: string }. returns: { data: { aliases?: string[], instrument_id: string, slug: string, category: string, name: string, description: string, geography?: string | null, venue?: string | null, currency: string, unit: string, price_type: string, frequency: string, source_id: string, source_name: string, source_url: string, attribution: string, value: string, observed_on: string<date>, previous_value?: string | null, previous_observed_on?: string<date> | null, high_value?: string | null, high_observed_on?: string<date> | null, low_value?: string | null, low_observed_on?: string<date> | null, fetched_at?: string<date-time> | null, last_checked?: string<date-time> | null, stale: boolean, observation_count: integer } }. errors: 401/422/429.

### yields: Government bond yields by country and maturity

- `GET /v1/yields/available`: Available bond yields. Find names for government bond yields with q.. params: { q: string, limit?: integer, offset?: integer }. returns: { data: { slug: string, name: string, aliases: string[], category: string, currency: string, unit: string, frequency: string }[], next_offset?: integer | null }. errors: 401/422/429.
- `GET /v1/yields/{slug}/history`: Bond yields history. Dated source observations, oldest first.. params: { slug: string, from?: string<date> | null, to?: string<date> | null, limit?: integer }. returns: { data: { observed_on: string<date>, value: string }[] }. errors: 401/422/429.
- `GET /v1/yields/{slug}`: Latest bond yield. Use a slug returned by getYieldsAvailable.. params: { slug: string }. returns: { data: { aliases?: string[], instrument_id: string, slug: string, category: string, name: string, description: string, geography?: string | null, venue?: string | null, currency: string, unit: string, price_type: string, frequency: string, source_id: string, source_name: string, source_url: string, attribution: string, value: string, observed_on: string<date>, previous_value?: string | null, previous_observed_on?: string<date> | null, high_value?: string | null, high_observed_on?: string<date> | null, low_value?: string | null, low_observed_on?: string<date> | null, fetched_at?: string<date-time> | null, last_checked?: string<date-time> | null, stale: boolean, observation_count: integer } }. errors: 401/422/429.

## Step 4: Error envelope

Every error is `{ "error": "<machine_code>", "message": "<human text>", "request_id": "<uuid>" }`. Branch on `error`, never on `message`. Status codes:

- 400: Bad request. A required input is missing. (`bad_request`)
- 401: Invalid, revoked, or missing API key. (`invalid_key`)
- 403: Free API calls used up, or the request did not pass through the gateway. (`quota_exceeded`, `forbidden`)
- 422: Unparseable input. The body did not validate against the schema. (`validation_error`)
- 429: Rate limit exceeded. Honor the `Retry-After` header. (`rate_limit_exceeded`)
- 503: An upstream dependency is unavailable. Retry with backoff. (`provider_unavailable`)
- 504: An upstream dependency timed out. Retry with backoff. (`provider_timeout`)

## Step 5: Implement

1. Add a typed client module in my stack with one function per endpoint above (base URL + auth header + JSON + timeout of 15s + the retry policy in Step 2).
2. Wire the endpoint(s) my use case needs into my app where the data is consumed; store `request_id` next to the result.
3. Handle every error code above explicitly; surface `message` to logs, not to end users.
4. Add one integration test per endpoint I use, hitting the live API with my key from the environment (skip when the key is absent).
5. Show me the diff and how to run the tests. Do not invent endpoints, fields, or prices that are not listed above.

## Example request

```bash
curl -X GET "https://api.economicsapi.com/v1/economics/available" \
  -H "Authorization: Bearer $API_KEY"
```