{"openapi":"3.1.0","info":{"title":"Anansi Data Public API — World Economic Database","version":"1.0.0-beta","description":"Programmatic, read-only access to Anansi's harmonized macroeconomic datasets.\n\n**Authentication:** every endpoint except `/status`, `/openapi.json`, and `/docs` (this reference) requires an API key, sent as `Authorization: Bearer ansi_live_...` (preferred) or `X-Api-Key: ansi_live_...`. Keys are shown once at creation — store them like passwords. Never put keys in query strings.\n\n**Dataset:** this document covers the World Economic Database (`wed`) only. Endpoints are rooted at `/wed/...`; other datasets have their own documents (see `/v1/docs`). `GET /datasets` lists them all with your entitlement per dataset.\n\n**Access:** World Economic Database requires an active subscription on the account that owns the key. `GET /datasets` shows whether your key is entitled. Trial subscriptions do not include API access.\n\n**Frequency:** series are published at several frequencies (see `/frequencies`); filter with the `frequency` parameter where offered.\n\n**Sources:** `/sources` returns the curated source hierarchy; sub-source identifiers from it are what `/sources/{name}` and the `source` filter accept.\n\n**Rate limits (beta):** 120 requests/min per key (30/min per IP unauthenticated). Every response carries `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`; 429s carry `Retry-After`. Monthly quotas are not yet enforced during beta.\n\n**Errors:** one envelope everywhere — `{ \"error\": { code, message, status, request_id } }`. Branch on `error.code`, never on message text. Include `request_id` (also in the `X-Request-Id` header) in support requests. Any endpoint may additionally return `500 internal_error` or `503 api_disabled` (maintenance kill switch); `quota_exceeded` is reserved for monthly quotas at GA and is not returned during beta.\n\n**Stability:** within `/v1` changes are additive only; breaking changes ship as `/v2`. Deprecations get 6 months' notice via `Deprecation`/`Sunset` headers.","contact":{"name":"Anansi Data","url":"https://anansidata.com"}},"servers":[{"url":"https://api.anansidata.com/v1","description":"Production host"}],"security":[{"bearerApiKey":[]},{"headerApiKey":[]}],"tags":[{"name":"service","description":"Liveness, spec, usage"},{"name":"discovery","description":"Datasets and dimension helpers for looping"},{"name":"catalog","description":"Series search and metadata"},{"name":"observations","description":"Time-series values"},{"name":"sources","description":"Source hierarchy and coverage"}],"paths":{"/status":{"get":{"tags":["service"],"summary":"Liveness + API version","security":[],"responses":{"200":{"description":"Service is up","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Status"}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/openapi.json":{"get":{"tags":["service"],"summary":"This specification","security":[],"responses":{"200":{"description":"OpenAPI 3.1 document","content":{"application/json":{"schema":{"type":"object"}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/openapi/{dataset}.json":{"get":{"tags":["service"],"summary":"This contract specialised to one dataset","description":"The OpenAPI document for a single dataset: its endpoints rooted at `/wed/...`, without the parameters or endpoints the dataset does not support (for example an annual-only dataset has no `frequency` filter and no `/frequencies`). Rendered by `/docs/{dataset}`.","security":[],"parameters":[{"name":"dataset","in":"path","required":true,"description":"Dataset id from GET /datasets (e.g. wed, gmd)","schema":{"type":"string"}}],"responses":{"200":{"description":"OpenAPI 3.1 document","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/usage":{"get":{"tags":["service"],"summary":"Current key's tier, limits, and usage this period","responses":{"200":{"description":"Usage","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Usage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/datasets":{"get":{"tags":["discovery"],"summary":"Dataset catalog with your entitlement per dataset","responses":{"200":{"description":"Datasets","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Dataset"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/wed/series":{"get":{"tags":["catalog"],"summary":"Search the series catalog","parameters":[{"name":"q","in":"query","description":"Full-text search (name, code, country, indicator, description). Treated literally — regex metacharacters are escaped.","schema":{"type":"string","maxLength":200}},{"$ref":"#/components/parameters/country"},{"$ref":"#/components/parameters/country_code"},{"$ref":"#/components/parameters/indicator"},{"$ref":"#/components/parameters/frequency"},{"$ref":"#/components/parameters/region"},{"name":"source","in":"query","description":"Series that include this source (see /wed/sources)","schema":{"type":"string"}},{"name":"start_date","in":"query","description":"Coverage overlap: series whose data extends past this date","schema":{"type":"string","format":"date"}},{"name":"end_date","in":"query","description":"Coverage overlap: series whose data begins before this date","schema":{"type":"string","format":"date"}},{"$ref":"#/components/parameters/page"},{"$ref":"#/components/parameters/per_page"},{"name":"sort","in":"query","schema":{"type":"string","enum":["country","indicator","last_update"],"default":"country"}}],"responses":{"200":{"description":"Matching series","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Series"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"400":{"$ref":"#/components/responses/InvalidParameter"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/wed/series/{series_code}":{"get":{"tags":["catalog"],"summary":"One series' metadata (lookup by series_code only)","parameters":[{"$ref":"#/components/parameters/series_code"}],"responses":{"200":{"description":"Series metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Series"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/wed/series/{series_code}/observations":{"get":{"tags":["observations"],"summary":"Time-series values for one series","parameters":[{"$ref":"#/components/parameters/series_code"},{"name":"start_date","in":"query","schema":{"type":"string","format":"date"}},{"name":"end_date","in":"query","schema":{"type":"string","format":"date"}},{"name":"limit","in":"query","description":"Max observations (cap 10000)","schema":{"type":"integer","minimum":1,"maximum":10000}},{"$ref":"#/components/parameters/format"}],"responses":{"200":{"description":"Observations (JSON or CSV per `format`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SeriesObservations"}},"text/csv":{"schema":{"type":"string","example":"date,value,is_forecast\n2024-01-01,27360.9,false"}}}},"400":{"$ref":"#/components/responses/InvalidParameter"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/wed/observations":{"get":{"tags":["observations"],"summary":"Bulk observations for explicit series codes","description":"Bulk export is by explicit `series_codes` only (max 50 during beta) — use the catalog and dimension endpoints to find codes. Unknown codes are reported in `missing` (JSON) or skipped (CSV); if none exist the request 404s.","parameters":[{"name":"series_codes","in":"query","required":true,"description":"Comma-separated series codes (max 50)","schema":{"type":"string"}},{"name":"start_date","in":"query","schema":{"type":"string","format":"date"}},{"name":"end_date","in":"query","schema":{"type":"string","format":"date"}},{"name":"format","in":"query","schema":{"type":"string","enum":["json","csv"],"default":"csv"}}],"responses":{"200":{"description":"Bulk observations (CSV by default)","content":{"text/csv":{"schema":{"type":"string","example":"series_code,name,country,indicator,frequency,date,value,is_forecast\n..."}},"application/json":{"schema":{"$ref":"#/components/schemas/BulkObservations"}}}},"400":{"$ref":"#/components/responses/InvalidParameter"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/wed/countries":{"get":{"tags":["discovery"],"summary":"Countries present in this dataset (with ISO codes and regions)","responses":{"200":{"description":"Countries","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Country"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/wed/indicators":{"get":{"tags":["discovery"],"summary":"Indicators present in this dataset (names + codes)","responses":{"200":{"description":"Indicators","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Indicator"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/wed/frequencies":{"get":{"tags":["discovery"],"summary":"Frequencies present in this dataset","responses":{"200":{"$ref":"#/components/responses/StringList"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/wed/units":{"get":{"tags":["discovery"],"summary":"Units present in this dataset","responses":{"200":{"$ref":"#/components/responses/StringList"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/wed/regions":{"get":{"tags":["discovery"],"summary":"Regions represented in this dataset (derived from country coverage)","responses":{"200":{"$ref":"#/components/responses/StringList"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/wed/stats":{"get":{"tags":["discovery"],"summary":"Dataset totals","responses":{"200":{"description":"Totals","content":{"application/json":{"schema":{"type":"object","properties":{"total_series":{"type":"integer"},"countries":{"type":"integer"},"indicators":{"type":"integer"},"frequencies":{"type":"integer"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/wed/sources":{"get":{"tags":["sources"],"summary":"Curated source hierarchy","responses":{"200":{"description":"Sources","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}},"description":"The masked, curated source families and their sub-sources. Use a sub-source identifier with /sources/{name} and the `source` filter."}},"/wed/sources/{name}":{"get":{"tags":["sources"],"summary":"Source detail + aggregate coverage statistics","parameters":[{"$ref":"#/components/parameters/source_name"}],"responses":{"200":{"description":"Source detail","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourceDetail"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/wed/sources/{name}/series":{"get":{"tags":["sources"],"summary":"Series carrying this source (filterable, paginated)","parameters":[{"$ref":"#/components/parameters/source_name"},{"$ref":"#/components/parameters/country"},{"$ref":"#/components/parameters/country_code"},{"$ref":"#/components/parameters/region"},{"$ref":"#/components/parameters/indicator"},{"$ref":"#/components/parameters/frequency"},{"name":"contributing_only","in":"query","description":"Only series where this source contributes to the harmonized values","schema":{"type":"boolean","default":false}},{"$ref":"#/components/parameters/page"},{"$ref":"#/components/parameters/per_page"}],"responses":{"200":{"description":"Series for this source","content":{"application/json":{"schema":{"type":"object","properties":{"source":{"type":"string"},"data":{"type":"array","items":{"$ref":"#/components/schemas/SeriesRef"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"400":{"$ref":"#/components/responses/InvalidParameter"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}}},"components":{"securitySchemes":{"bearerApiKey":{"type":"http","scheme":"bearer","bearerFormat":"ansi_live_...","description":"Authorization: Bearer ansi_live_..."},"headerApiKey":{"type":"apiKey","in":"header","name":"X-Api-Key"}},"parameters":{"series_code":{"name":"series_code","in":"path","required":true,"description":"Series code (case-insensitive)","schema":{"type":"string"}},"source_name":{"name":"name","in":"path","required":true,"description":"Source name from /wed/sources","schema":{"type":"string"}},"country":{"name":"country","in":"query","description":"Comma-separated canonical country names","schema":{"type":"string"}},"country_code":{"name":"country_code","in":"query","description":"Comma-separated ISO3 codes, case-insensitive (loop-safe alternative to country)","schema":{"type":"string"}},"region":{"name":"region","in":"query","description":"Comma-separated continents (Africa, Americas, Asia, Europe, Oceania); expands to member countries. With country_code: intersection","schema":{"type":"string"}},"indicator":{"name":"indicator","in":"query","description":"Comma-separated indicator names","schema":{"type":"string"}},"frequency":{"name":"frequency","in":"query","description":"Comma-separated frequencies (e.g. Annual, Quarterly, Monthly)","schema":{"type":"string"}},"page":{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},"per_page":{"name":"per_page","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},"format":{"name":"format","in":"query","schema":{"type":"string","enum":["json","csv"],"default":"json"}}},"responses":{"Unauthorized":{"description":"Missing, invalid, or revoked API key (`invalid_api_key`, `key_revoked`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"No active subscription for this dataset (`not_entitled`), trial access (`trial_no_api`), or the series belongs to an add-on package the key's account does not hold (`addon_required`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Unknown dataset (`dataset_not_found`) or resource (`not_found`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InvalidParameter":{"description":"Validation failure — the message names the parameter (`invalid_parameter`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Per-minute limit exceeded (`rate_limit_exceeded`); honor `Retry-After`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"StringList":{"description":"Distinct values","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"string"}}}}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Machine-readable code — branch on this. `api_disabled` (503) and `internal_error` (500) can occur on any endpoint; `quota_exceeded` is reserved for GA monthly quotas and not returned during beta.","enum":["invalid_api_key","key_revoked","dataset_not_found","not_entitled","trial_no_api","addon_required","not_found","invalid_parameter","rate_limit_exceeded","quota_exceeded","api_disabled","internal_error"]},"message":{"type":"string"},"status":{"type":"integer"},"request_id":{"type":["string","null"]}}}}},"Status":{"type":"object","properties":{"status":{"type":"string"},"version":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}},"Pagination":{"type":"object","properties":{"total":{"type":"integer"},"page":{"type":"integer"},"per_page":{"type":"integer"},"pages":{"type":"integer"}}},"Dataset":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"adapter_family":{"type":"string"},"entitled":{"type":"boolean","description":"Whether THIS key may access the dataset's data endpoints"},"trial_only":{"type":"boolean","description":"Present (true) when the account holds only a trial — API access requires a paid subscription"},"capabilities":{"type":"object","properties":{"endpoints":{"type":"array","items":{"type":"string"}},"formats":{"type":"array","items":{"type":"string"}}}}}},"Usage":{"type":"object","properties":{"key_id":{"type":"string"},"tier":{"type":"string"},"rate_limit":{"type":"object","properties":{"per_minute":{"type":"integer"}}},"quota":{"type":"object","properties":{"monthly":{"type":["integer","null"],"description":"null during beta — quotas not yet enforced"},"used_this_period":{"type":"integer"},"period":{"type":"string","example":"2026-07"},"resets_at":{"type":"string","format":"date-time"}}}}},"Country":{"type":"object","properties":{"name":{"type":"string"},"code":{"type":["string","null"],"description":"ISO3"},"region":{"type":["string","null"],"description":"Continent; null for aggregates (e.g. World)"}}},"Indicator":{"type":"object","properties":{"name":{"type":"string"},"code":{"type":["string","null"]}}},"SeriesRef":{"type":"object","properties":{"series_code":{"type":"string"},"name":{"type":"string"},"country":{"type":"string"},"country_code":{"type":["string","null"]},"indicator":{"type":"string"},"frequency":{"type":"string"}}},"Series":{"type":"object","properties":{"series_code":{"type":"string"},"name":{"type":"string"},"country":{"type":"string"},"country_code":{"type":["string","null"]},"region":{"type":["string","null"]},"indicator":{"type":"string"},"indicator_short":{"type":["string","null"]},"frequency":{"type":"string"},"unit":{"type":["string","null"]},"description":{"type":["string","null"]},"stats":{"type":"object","properties":{"start_date":{"type":"string","format":"date-time"},"end_date":{"type":"string","format":"date-time"},"observation_count":{"type":"integer"},"last_value":{"type":"number"},"last_update":{"type":"string","format":"date-time"}}},"available_sources":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"display_name":{"type":["string","null"]},"is_contributing":{"type":"boolean"},"coverage":{"type":"object","properties":{"start_date":{"type":"string","format":"date-time"},"end_date":{"type":"string","format":"date-time"},"data_points":{"type":"integer"}}}}}}}},"Observation":{"type":"object","properties":{"date":{"type":"string","format":"date"},"value":{"type":["number","null"]},"is_forecast":{"type":"boolean"}}},"SeriesObservations":{"type":"object","properties":{"series_code":{"type":"string"},"name":{"type":"string"},"unit":{"type":["string","null"]},"frequency":{"type":"string"},"observations":{"type":"array","items":{"$ref":"#/components/schemas/Observation"}}}},"BulkObservations":{"type":"object","properties":{"data":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/SeriesRef"},{"type":"object","properties":{"observations":{"type":"array","items":{"$ref":"#/components/schemas/Observation"}}}}]}},"missing":{"type":"array","items":{"type":"string"},"description":"Requested codes that do not exist"}}},"SourceDetail":{"type":"object","properties":{"source":{"type":"object","properties":{"name":{"type":"string"},"display_name":{"type":"string"},"parent_source":{"type":["string","null"]}}},"statistics":{"type":"object","properties":{"series_count":{"type":"integer"},"contributing_series_count":{"type":"integer"},"total_data_points":{"type":"integer"},"date_range":{"type":"object","properties":{"earliest":{"type":["string","null"],"format":"date-time"},"latest":{"type":["string","null"],"format":"date-time"}}}}}}}}},"x-dataset":{"id":"wed","name":"World Economic Database","access":"subscription","fixed_frequency":null}}