Integration Prompt

# Integrate EconomicsAPI into my application

You are integrating EconomicsAPI — Clean economic data for AI agents — into my application end-to-end. 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/llms-full.md (Markdown) · 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.
- Usage is metered per call in credits; the dashboard shows balance and usage.

## Step 3 — Endpoints

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

- `GET /v1/countries` — List covered countries and groups. returns: { data: { country_id: string, name: string, slug: string, iso2?: string | null, kind: string, groups?: string[] }[] }. errors: 401/429.
- `GET /v1/indicators` — List indicators with slugs, units, and search aliases. 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/429.
- `GET /v1/latest` — Latest values with previous/high/low and source attribution. 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, frequency: string, adjustment?: string | null, source_name: string, source_url: string, license_id: string, attribution_text: string, first_value_date?: string<date> | null, last_update?: string<date-time> | null }[] }. errors: 401/422/429.
- `GET /v1/history` — Historical observations, optionally transformed. 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, last_update?: string<date-time> | null }[], next_cursor?: string | null }. errors: 401/422/429.
- `GET /v1/search` — Resolve free text to countries, indicators, and series. 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` — Series whose data changed since a timestamp. 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.

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

- `GET /v1/trade` — Raw trade observations. 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` — Aggregated trade metrics. 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` — Data coverage per country. What we hold per country: the yearly span and the monthly span.. returns: { data: { country: string, 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/429.
- `GET /v1/trade/products` — Search 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 metadata. 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 trade series. 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` — Top markets for a product. 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` — Search countries. Search countries by 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 }[], request_id?: string, duration_ms?: integer }. errors: 401/422/429.
- `GET /v1/trade/countries/{cid}` — Country metadata. Metadata for one country (id = ISO alpha-2).. params: { cid: string }. returns: { data: { id: string, iso3?: string | null, name: string, is_group: boolean, region?: string | null, note?: string | null }, request_id?: string, duration_ms?: integer }. errors: 401/422/429.
- `GET /v1/trade/countries/{cid}/imports` — Country import series. 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 export series. 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 trading 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 product mix. 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.

## 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 — Credit quota exhausted, 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/countries" \
  -H "Authorization: Bearer $API_KEY"
```