{ "openapi": "3.1.0", "info": { "title": "economicsapi API", "description": "economicsapi — official economic statistics and global trade data, one API.\n\n## Authentication\n\nAll requests require a Bearer API key from your dashboard.\n\n```http\nAuthorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxx\n```\n\n## Rate limits\n\nPer-key sliding window. Exceeding it returns `429`.", "version": "1.0.0", "contact": { "email": "hello@economicsapi.com" } }, "servers": [ { "url": "https://api.economicsapi.com", "description": "Production" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "economics", "description": "GDP, prices, labour, money, government and external-sector indicators for 50 countries" }, { "name": "trade", "description": "Bilateral goods trade for 41 countries, 2015 to today" } ], "paths": { "/v1/countries": { "get": { "tags": [ "economics" ], "summary": "List covered countries and groups", "operationId": "listCountries", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CountriesResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/indicators": { "get": { "tags": [ "economics" ], "summary": "List indicators with slugs, units, and search aliases", "operationId": "listIndicators", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IndicatorsResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/latest": { "get": { "tags": [ "economics" ], "summary": "Latest values with previous/high/low and source attribution", "operationId": "getLatest", "parameters": [ { "name": "country", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO3, slug, or group token (g20, emu); comma-listable", "title": "Country" }, "description": "ISO3, slug, or group token (g20, emu); comma-listable" }, { "name": "indicator", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "kpi_id, slug, or alias; comma-listable", "title": "Indicator" }, "description": "kpi_id, slug, or alias; comma-listable" }, { "name": "group", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "indicator group filter, e.g. prices", "title": "Group" }, "description": "indicator group filter, e.g. prices" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LatestResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/history": { "get": { "tags": [ "economics" ], "summary": "Historical observations, optionally transformed", "operationId": "getHistory", "parameters": [ { "name": "country", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO3, slug, or group token; comma-listable", "title": "Country" }, "description": "ISO3, slug, or group token; comma-listable" }, { "name": "indicator", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "kpi_id, slug, or alias; comma-listable", "title": "Indicator" }, "description": "kpi_id, slug, or alias; comma-listable" }, { "name": "from", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "YYYY or YYYY-MM-DD", "title": "From" }, "description": "YYYY or YYYY-MM-DD" }, { "name": "to", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "YYYY or YYYY-MM-DD", "title": "To" }, "description": "YYYY or YYYY-MM-DD" }, { "name": "transform", "in": "query", "required": false, "schema": { "type": "string", "description": "none | yoy | mom | log_diff | 3mma", "default": "none", "title": "Transform" }, "description": "none | yoy | mom | log_diff | 3mma" }, { "name": "cursor", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "next_cursor from the previous page", "title": "Cursor" }, "description": "next_cursor from the previous page" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HistoryResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/search": { "get": { "tags": [ "economics" ], "summary": "Resolve free text to countries, indicators, and series", "operationId": "search", "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "description": "free text, e.g. 'inflation' or 'mexico'", "title": "Q" }, "description": "free text, e.g. 'inflation' or 'mexico'" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "default": 20, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/updates": { "get": { "tags": [ "economics" ], "summary": "Series whose data changed since a timestamp", "operationId": "getUpdates", "parameters": [ { "name": "since", "in": "query", "required": true, "schema": { "type": "string", "description": "ISO datetime, e.g. 2026-09-01T00:00:00Z", "title": "Since" }, "description": "ISO datetime, e.g. 2026-09-01T00:00:00Z" }, { "name": "country", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO3, slug, or group token; comma-listable", "title": "Country" }, "description": "ISO3, slug, or group token; comma-listable" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatesResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/trade": { "get": { "tags": [ "trade" ], "summary": "Raw trade observations", "description": "Individual exporter→importer→product→year flows, filtered by reporter, partner, product, flow direction and period.", "operationId": "getTrade", "parameters": [ { "name": "reporter", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reporter" } }, { "name": "partner", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Partner" } }, { "name": "product", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Product" } }, { "name": "flow", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Flow" } }, { "name": "from", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "From" } }, { "name": "to", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "To" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 10000, "minimum": 1, "default": 1000, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope_list_TradeObservation__" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/trade/summary": { "get": { "tags": [ "trade" ], "summary": "Aggregated trade metrics", "description": "Total value, quantity, growth, unit value, top partners and partner concentration (HHI) for any reporter/partner/product/period selection.", "operationId": "getTradeSummary", "parameters": [ { "name": "reporter", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reporter" } }, { "name": "partner", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Partner" } }, { "name": "product", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Product" } }, { "name": "flow", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Flow" } }, { "name": "from", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "From" } }, { "name": "to", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "To" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope_TradeSummary_" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/trade/monthly": { "get": { "tags": [ "trade" ], "summary": "Monthly trade", "description": "Monthly bilateral flows, one value per exporter, importer, product and month. Filter by exporter, importer, product and period; group_by aggregates by period, exporter, importer or hs6.", "operationId": "getTradeMonthly", "parameters": [ { "name": "exporter", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Exporter" } }, { "name": "importer", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Importer" } }, { "name": "product", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Product" } }, { "name": "from", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "From" } }, { "name": "to", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "To" } }, { "name": "method", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Method" } }, { "name": "group_by", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Group By" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 10000, "minimum": 1, "default": 1000, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope_Union_list_MonthlyObservation___list_MonthlyGroupedPoint___" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/trade/coverage": { "get": { "tags": [ "trade" ], "summary": "Data coverage per country", "description": "What we hold per country: the yearly span and the monthly span.", "operationId": "getCoverage", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope_list_CoverageRow__" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/trade/products": { "get": { "tags": [ "trade" ], "summary": "Search products", "description": "Search the HS6 product catalog by code prefix or name.", "operationId": "searchProducts", "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "title": "Q" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 500, "minimum": 1, "default": 50, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope_list_ProductRow__" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/trade/products/{pid}": { "get": { "tags": [ "trade" ], "summary": "Product metadata", "description": "Metadata for an HS6 code ('390210', 'hs:390210') or a 2-4 digit chapter prefix.", "operationId": "getProduct", "parameters": [ { "name": "pid", "in": "path", "required": true, "schema": { "type": "string", "title": "Pid" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope_ProductDetail_" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/trade/products/{pid}/history": { "get": { "tags": [ "trade" ], "summary": "Product trade series", "description": "Annual trade series for one product, optionally filtered by reporter/partner and flow direction.", "operationId": "getProductHistory", "parameters": [ { "name": "pid", "in": "path", "required": true, "schema": { "type": "string", "title": "Pid" } }, { "name": "reporter", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reporter" } }, { "name": "partner", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Partner" } }, { "name": "flow", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Flow" } }, { "name": "from", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "From" } }, { "name": "to", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "To" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope_list_GroupedPoint__" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/trade/products/{pid}/markets": { "get": { "tags": [ "trade" ], "summary": "Top markets for a product", "description": "Top exporting and importing countries for a product over a period.", "operationId": "getProductMarkets", "parameters": [ { "name": "pid", "in": "path", "required": true, "schema": { "type": "string", "title": "Pid" } }, { "name": "from", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "From" } }, { "name": "to", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "To" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 200, "minimum": 1, "default": 20, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope_Markets_" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/trade/countries": { "get": { "tags": [ "trade" ], "summary": "Search countries", "description": "Search countries by name, ISO alpha-2 or alpha-3 code.", "operationId": "searchTradeCountries", "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "title": "Q" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 500, "minimum": 1, "default": 50, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope_list_CountryRow__" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/trade/countries/{cid}": { "get": { "tags": [ "trade" ], "summary": "Country metadata", "description": "Metadata for one country (id = ISO alpha-2).", "operationId": "getTradeCountry", "parameters": [ { "name": "cid", "in": "path", "required": true, "schema": { "type": "string", "title": "Cid" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope_CountryDetail_" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/trade/countries/{cid}/imports": { "get": { "tags": [ "trade" ], "summary": "Country import series", "description": "Annual import value/quantity series for one country, optionally filtered by partner and product.", "operationId": "getCountryImports", "parameters": [ { "name": "cid", "in": "path", "required": true, "schema": { "type": "string", "title": "Cid" } }, { "name": "partner", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Partner" } }, { "name": "product", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Product" } }, { "name": "from", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "From" } }, { "name": "to", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "To" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope_list_GroupedPoint__" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/trade/countries/{cid}/exports": { "get": { "tags": [ "trade" ], "summary": "Country export series", "description": "Annual export value/quantity series for one country, optionally filtered by partner and product.", "operationId": "getCountryExports", "parameters": [ { "name": "cid", "in": "path", "required": true, "schema": { "type": "string", "title": "Cid" } }, { "name": "partner", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Partner" } }, { "name": "product", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Product" } }, { "name": "from", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "From" } }, { "name": "to", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "To" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope_list_GroupedPoint__" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/trade/countries/{cid}/partners": { "get": { "tags": [ "trade" ], "summary": "Country trading partners", "description": "A country's partners ranked by trade value, for either flow direction, optionally per product.", "operationId": "getCountryPartners", "parameters": [ { "name": "cid", "in": "path", "required": true, "schema": { "type": "string", "title": "Cid" } }, { "name": "flow", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Flow" } }, { "name": "product", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Product" } }, { "name": "from", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "From" } }, { "name": "to", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "To" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 500, "minimum": 1, "default": 50, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope_list_GroupedPoint__" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ] } }, "/v1/trade/countries/{cid}/products": { "get": { "tags": [ "trade" ], "summary": "Country product mix", "description": "What a country trades, grouped by HS6 product and ranked by value, for either flow direction.", "operationId": "getCountryProducts", "parameters": [ { "name": "cid", "in": "path", "required": true, "schema": { "type": "string", "title": "Cid" } }, { "name": "flow", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Flow" } }, { "name": "from", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "From" } }, { "name": "to", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "To" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 500, "minimum": 1, "default": 50, "title": "Limit" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope_list_GroupedPoint__" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } }, "security": [ { "bearerAuth": [] } ] } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "sk_live_xxxxxxxxxxxxxxxxxxxx", "description": "API key from your economicsapi dashboard" } }, "responses": { "Unauthorized": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "invalid_key", "message": "Invalid or missing API key" } } } }, "RateLimited": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "rate_limit_exceeded", "message": "Rate limit exceeded" } } } } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } } }, "CountriesResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/CountryOut" }, "type": "array", "title": "Data" } }, "type": "object", "required": [ "data" ], "title": "CountriesResponse" }, "CountryOut": { "properties": { "country_id": { "type": "string", "title": "Country Id", "description": "ISO 3166-1 alpha-3; Euro Area is EMU" }, "name": { "type": "string", "title": "Name" }, "slug": { "type": "string", "title": "Slug" }, "iso2": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Iso2" }, "kind": { "type": "string", "title": "Kind", "description": "iso | aggregate" }, "groups": { "items": { "type": "string" }, "type": "array", "title": "Groups", "default": [] } }, "type": "object", "required": [ "country_id", "name", "slug", "kind" ], "title": "CountryOut" }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "HistoryResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/ObservationOut" }, "type": "array", "title": "Data" }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Next Cursor" } }, "type": "object", "required": [ "data" ], "title": "HistoryResponse" }, "IndicatorOut": { "properties": { "kpi_id": { "type": "string", "title": "Kpi Id" }, "slug": { "type": "string", "title": "Slug" }, "name": { "type": "string", "title": "Name" }, "group": { "type": "string", "title": "Group", "description": "gdp | prices | labour | money | government | external | activity" }, "unit": { "type": "string", "title": "Unit" }, "unit_code": { "type": "string", "title": "Unit Code" }, "frequency": { "type": "string", "title": "Frequency", "description": "best available frequency: monthly | quarterly | annual" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "aliases": { "items": { "type": "string" }, "type": "array", "title": "Aliases", "default": [] } }, "type": "object", "required": [ "kpi_id", "slug", "name", "group", "unit", "unit_code", "frequency" ], "title": "IndicatorOut" }, "IndicatorsResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/IndicatorOut" }, "type": "array", "title": "Data" } }, "type": "object", "required": [ "data" ], "title": "IndicatorsResponse" }, "LatestCard": { "properties": { "series_id": { "type": "string", "title": "Series Id", "description": "{ISO3}.{kpi_id}, e.g. MEX.PR.CPI.Yoy" }, "country_id": { "type": "string", "title": "Country Id" }, "country": { "type": "string", "title": "Country" }, "kpi_id": { "type": "string", "title": "Kpi Id" }, "indicator": { "type": "string", "title": "Indicator" }, "slug": { "type": "string", "title": "Slug" }, "group": { "type": "string", "title": "Group" }, "latest_value": { "type": "number", "title": "Latest Value" }, "latest_value_date": { "type": "string", "format": "date", "title": "Latest Value Date" }, "previous_value": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Previous Value" }, "previous_value_date": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Previous Value Date" }, "highest_value": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Highest Value" }, "highest_value_date": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Highest Value Date" }, "lowest_value": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Lowest Value" }, "lowest_value_date": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Lowest Value Date" }, "unit": { "type": "string", "title": "Unit" }, "unit_code": { "type": "string", "title": "Unit Code" }, "frequency": { "type": "string", "title": "Frequency" }, "adjustment": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Adjustment" }, "source_name": { "type": "string", "title": "Source Name" }, "source_url": { "type": "string", "title": "Source Url" }, "license_id": { "type": "string", "title": "License Id" }, "attribution_text": { "type": "string", "title": "Attribution Text" }, "first_value_date": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "First Value Date" }, "last_update": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Last Update" } }, "type": "object", "required": [ "series_id", "country_id", "country", "kpi_id", "indicator", "slug", "group", "latest_value", "latest_value_date", "unit", "unit_code", "frequency", "source_name", "source_url", "license_id", "attribution_text" ], "title": "LatestCard" }, "LatestResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/LatestCard" }, "type": "array", "title": "Data" } }, "type": "object", "required": [ "data" ], "title": "LatestResponse" }, "ObservationOut": { "properties": { "series_id": { "type": "string", "title": "Series Id" }, "country_id": { "type": "string", "title": "Country Id" }, "kpi_id": { "type": "string", "title": "Kpi Id" }, "date": { "type": "string", "format": "date", "title": "Date", "description": "period end (month/quarter/year end)" }, "value": { "type": "number", "title": "Value" }, "frequency": { "type": "string", "title": "Frequency" }, "obs_status": { "type": "string", "title": "Obs Status", "default": "A" }, "last_update": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "title": "Last Update" } }, "type": "object", "required": [ "series_id", "country_id", "kpi_id", "date", "value", "frequency" ], "title": "ObservationOut" }, "SearchHit": { "properties": { "type": { "type": "string", "title": "Type", "description": "series | country | indicator" }, "title": { "type": "string", "title": "Title" }, "series_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Series Id" }, "country_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Country Id" }, "kpi_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Kpi Id" }, "slug": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Slug" }, "latest_value": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Latest Value" }, "latest_value_date": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Latest Value Date" }, "unit": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Unit" }, "frequency": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Frequency" } }, "type": "object", "required": [ "type", "title" ], "title": "SearchHit" }, "SearchResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/SearchHit" }, "type": "array", "title": "Data" } }, "type": "object", "required": [ "data" ], "title": "SearchResponse" }, "UpdateRow": { "properties": { "series_id": { "type": "string", "title": "Series Id" }, "country_id": { "type": "string", "title": "Country Id" }, "kpi_id": { "type": "string", "title": "Kpi Id" }, "slug": { "type": "string", "title": "Slug" }, "last_update": { "type": "string", "format": "date-time", "title": "Last Update" } }, "type": "object", "required": [ "series_id", "country_id", "kpi_id", "slug", "last_update" ], "title": "UpdateRow" }, "UpdatesResponse": { "properties": { "data": { "items": { "$ref": "#/components/schemas/UpdateRow" }, "type": "array", "title": "Data" } }, "type": "object", "required": [ "data" ], "title": "UpdatesResponse" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" }, "input": { "title": "Input" }, "ctx": { "type": "object", "title": "Context" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" }, "CountryDetail": { "properties": { "id": { "type": "string", "title": "Id" }, "iso3": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Iso3" }, "name": { "type": "string", "title": "Name" }, "is_group": { "type": "boolean", "title": "Is Group" }, "region": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Region" }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Note" } }, "type": "object", "required": [ "id", "name", "is_group" ], "title": "CountryDetail" }, "CountryRow": { "properties": { "id": { "type": "string", "title": "Id" }, "iso3": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Iso3" }, "name": { "type": "string", "title": "Name" }, "is_group": { "type": "boolean", "title": "Is Group" } }, "type": "object", "required": [ "id", "name", "is_group" ], "title": "CountryRow" }, "CoverageRow": { "properties": { "country": { "type": "string", "title": "Country" }, "yearly_first": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Yearly First" }, "yearly_last": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Yearly Last" }, "monthly_first": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Monthly First" }, "monthly_last": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Monthly Last" } }, "type": "object", "required": [ "country", "yearly_first", "yearly_last", "monthly_first", "monthly_last" ], "title": "CoverageRow", "description": "What we hold for one country. Monthly bounds come from the served\nverdicts, so a country appears once its data is live." }, "Envelope_CountryDetail_": { "properties": { "data": { "$ref": "#/components/schemas/CountryDetail" }, "request_id": { "type": "string", "title": "Request Id", "default": "" }, "duration_ms": { "type": "integer", "title": "Duration Ms", "default": 0 } }, "type": "object", "required": [ "data" ], "title": "Envelope[CountryDetail]" }, "Envelope_Markets_": { "properties": { "data": { "$ref": "#/components/schemas/Markets" }, "request_id": { "type": "string", "title": "Request Id", "default": "" }, "duration_ms": { "type": "integer", "title": "Duration Ms", "default": 0 } }, "type": "object", "required": [ "data" ], "title": "Envelope[Markets]" }, "Envelope_ProductDetail_": { "properties": { "data": { "$ref": "#/components/schemas/ProductDetail" }, "request_id": { "type": "string", "title": "Request Id", "default": "" }, "duration_ms": { "type": "integer", "title": "Duration Ms", "default": 0 } }, "type": "object", "required": [ "data" ], "title": "Envelope[ProductDetail]" }, "Envelope_TradeSummary_": { "properties": { "data": { "$ref": "#/components/schemas/TradeSummary" }, "request_id": { "type": "string", "title": "Request Id", "default": "" }, "duration_ms": { "type": "integer", "title": "Duration Ms", "default": 0 } }, "type": "object", "required": [ "data" ], "title": "Envelope[TradeSummary]" }, "Envelope_Union_list_MonthlyObservation___list_MonthlyGroupedPoint___": { "properties": { "data": { "anyOf": [ { "items": { "$ref": "#/components/schemas/MonthlyObservation" }, "type": "array" }, { "items": { "$ref": "#/components/schemas/MonthlyGroupedPoint" }, "type": "array" } ], "title": "Data" }, "request_id": { "type": "string", "title": "Request Id", "default": "" }, "duration_ms": { "type": "integer", "title": "Duration Ms", "default": 0 } }, "type": "object", "required": [ "data" ], "title": "Envelope[Union[list[MonthlyObservation], list[MonthlyGroupedPoint]]]" }, "Envelope_list_CountryRow__": { "properties": { "data": { "items": { "$ref": "#/components/schemas/CountryRow" }, "type": "array", "title": "Data" }, "request_id": { "type": "string", "title": "Request Id", "default": "" }, "duration_ms": { "type": "integer", "title": "Duration Ms", "default": 0 } }, "type": "object", "required": [ "data" ], "title": "Envelope[list[CountryRow]]" }, "Envelope_list_CoverageRow__": { "properties": { "data": { "items": { "$ref": "#/components/schemas/CoverageRow" }, "type": "array", "title": "Data" }, "request_id": { "type": "string", "title": "Request Id", "default": "" }, "duration_ms": { "type": "integer", "title": "Duration Ms", "default": 0 } }, "type": "object", "required": [ "data" ], "title": "Envelope[list[CoverageRow]]" }, "Envelope_list_GroupedPoint__": { "properties": { "data": { "items": { "$ref": "#/components/schemas/GroupedPoint" }, "type": "array", "title": "Data" }, "request_id": { "type": "string", "title": "Request Id", "default": "" }, "duration_ms": { "type": "integer", "title": "Duration Ms", "default": 0 } }, "type": "object", "required": [ "data" ], "title": "Envelope[list[GroupedPoint]]" }, "Envelope_list_ProductRow__": { "properties": { "data": { "items": { "$ref": "#/components/schemas/ProductRow" }, "type": "array", "title": "Data" }, "request_id": { "type": "string", "title": "Request Id", "default": "" }, "duration_ms": { "type": "integer", "title": "Duration Ms", "default": 0 } }, "type": "object", "required": [ "data" ], "title": "Envelope[list[ProductRow]]" }, "Envelope_list_TradeObservation__": { "properties": { "data": { "items": { "$ref": "#/components/schemas/TradeObservation" }, "type": "array", "title": "Data" }, "request_id": { "type": "string", "title": "Request Id", "default": "" }, "duration_ms": { "type": "integer", "title": "Duration Ms", "default": 0 } }, "type": "object", "required": [ "data" ], "title": "Envelope[list[TradeObservation]]" }, "GroupedPoint": { "properties": { "period": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Period" }, "partner": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Partner" }, "exporter": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Exporter" }, "importer": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Importer" }, "hs6": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Hs6" }, "value_usd": { "type": "number", "title": "Value Usd" }, "quantity": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Quantity" }, "flow_count": { "type": "integer", "title": "Flow Count" } }, "type": "object", "required": [ "value_usd", "quantity", "flow_count" ], "title": "GroupedPoint", "description": "One row of a grouped query; exactly one of the key fields is set." }, "Markets": { "properties": { "top_exporters": { "items": { "$ref": "#/components/schemas/GroupedPoint" }, "type": "array", "title": "Top Exporters" }, "top_importers": { "items": { "$ref": "#/components/schemas/GroupedPoint" }, "type": "array", "title": "Top Importers" } }, "type": "object", "required": [ "top_exporters", "top_importers" ], "title": "Markets" }, "MonthlyGroupedPoint": { "properties": { "period": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ], "title": "Period" }, "exporter": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Exporter" }, "importer": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Importer" }, "hs6": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Hs6" }, "value_usd": { "type": "number", "title": "Value Usd" }, "flow_count": { "type": "integer", "title": "Flow Count" } }, "type": "object", "required": [ "value_usd", "flow_count" ], "title": "MonthlyGroupedPoint" }, "MonthlyObservation": { "properties": { "exporter": { "type": "string", "title": "Exporter" }, "importer": { "type": "string", "title": "Importer" }, "hs6": { "type": "string", "title": "Hs6" }, "period": { "type": "string", "format": "date", "title": "Period" }, "value_usd": { "type": "number", "title": "Value Usd" }, "method": { "type": "string", "title": "Method" } }, "type": "object", "required": [ "exporter", "importer", "hs6", "period", "value_usd", "method" ], "title": "MonthlyObservation", "description": "One reconciled monthly flow. Same shape as the annual table, plus the\nmethod that produced it." }, "PeriodPoint": { "properties": { "period": { "type": "string", "title": "Period" }, "value_usd": { "type": "number", "title": "Value Usd" } }, "type": "object", "required": [ "period", "value_usd" ], "title": "PeriodPoint" }, "ProductDetail": { "properties": { "id": { "type": "string", "title": "Id" }, "matches": { "items": { "$ref": "#/components/schemas/ProductMatch" }, "type": "array", "title": "Matches" } }, "type": "object", "required": [ "id", "matches" ], "title": "ProductDetail" }, "ProductMatch": { "properties": { "hs6": { "type": "string", "title": "Hs6" }, "hs_version": { "type": "integer", "title": "Hs Version" }, "name": { "type": "string", "title": "Name" }, "parent_hs4": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Parent Hs4" } }, "type": "object", "required": [ "hs6", "hs_version", "name" ], "title": "ProductMatch" }, "ProductRow": { "properties": { "hs6": { "type": "string", "title": "Hs6" }, "hs_version": { "type": "integer", "title": "Hs Version" }, "name": { "type": "string", "title": "Name" } }, "type": "object", "required": [ "hs6", "hs_version", "name" ], "title": "ProductRow" }, "TopPartner": { "properties": { "partner": { "type": "string", "title": "Partner" }, "value_usd": { "type": "number", "title": "Value Usd" }, "share": { "type": "number", "title": "Share" } }, "type": "object", "required": [ "partner", "value_usd", "share" ], "title": "TopPartner" }, "TradeObservation": { "properties": { "exporter": { "type": "string", "title": "Exporter" }, "importer": { "type": "string", "title": "Importer" }, "hs6": { "type": "string", "title": "Hs6" }, "hs_version": { "type": "integer", "title": "Hs Version" }, "period": { "type": "string", "format": "date", "title": "Period" }, "granularity": { "type": "string", "title": "Granularity" }, "value_usd": { "type": "number", "title": "Value Usd" }, "quantity": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Quantity" }, "quantity_unit": { "type": "string", "title": "Quantity Unit" } }, "type": "object", "required": [ "exporter", "importer", "hs6", "hs_version", "period", "granularity", "value_usd", "quantity", "quantity_unit" ], "title": "TradeObservation" }, "TradeSummary": { "properties": { "trade_value": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Trade Value" }, "quantity": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Quantity" }, "growth": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Growth" }, "unit_value": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Unit Value" }, "top_partners": { "items": { "$ref": "#/components/schemas/TopPartner" }, "type": "array", "title": "Top Partners" }, "partner_concentration": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Partner Concentration" }, "periods": { "items": { "$ref": "#/components/schemas/PeriodPoint" }, "type": "array", "title": "Periods" } }, "type": "object", "required": [ "trade_value", "quantity", "growth", "unit_value", "top_partners", "partner_concentration", "periods" ], "title": "TradeSummary" } } } }