> ## Documentation Index > Fetch the complete documentation index at: https://developer.hayinsights.com/llms.txt > Use this file to discover all available pages before exploring further. # Economic data series > Time series for a selected macroeconomic indicator — GDP, CPI, PCE or import-export — for a country, over a chosen look-back window. ## OpenAPI ````yaml /openapi.yaml get /openapi/v1/macro/economic-data openapi: 3.1.0 info: title: HayInsights Open API version: 0.1.0 description: > Programmatic access to the **HayInsights** financial-data hub — commodities, crypto, ETF, FX, macroeconomic and real-estate datasets, served from a single API surface under `/openapi/v1/*`. This specification is the **single source of truth** for the public API surface — shared by SDK codegen, the reference docs, and (later) the mock server / contract tests. ## Authentication Every request must carry your API key in the `X-API-Key` header. There is a single authentication tier — no request signing. Create and manage keys in the HayInsights dashboard (Account → API keys). See **Authentication**. ## Plans & quota Access to each data domain and your request quota are governed by the subscription plan attached to your key. Each endpoint consumes a **weighted** amount of your per-minute quota; every response carries `X-RateLimit-*` headers. See **Rate limits** and **Plans & features**. contact: {} servers: - url: https://api.hayinsights.com description: Production security: - HayInsightsApiKey: [] tags: - name: Commodities description: >- Spot prices, top movers, gold–DXY correlation and historical series for energy, metals and agricultural commodities. - name: Crypto description: >- Crypto market overview, dominance, bubble map, on-chain and derivatives metrics. - name: ETF description: >- Exchange-traded fund listings, performance & net-flow rankings, heatmap, holdings, NAV growth and fund composition. - name: FX description: >- Foreign-exchange summary, live table, 90-day correlation matrix and the emerging-market stress monitor. - name: Macro description: >- Macroeconomic indicators — GDP, CPI/PCE, exchange rates, population, central-government debt and policy rates / bond yields. - name: Real Estate description: >- Real-estate statistics, land prices, administrative geography (provinces / wards) and choropleth GeoJSON, by country. paths: /openapi/v1/macro/economic-data: get: tags: - Macro summary: Economic data series description: | Time series for a selected macroeconomic indicator — GDP, CPI, PCE or import-export — for a country, over a chosen look-back window. operationId: macroEconomicData parameters: - name: type in: query required: true description: | Macroeconomic indicator to return. | Value | Description | | --- | --- | | `gdp` | Gross Domestic Product | | `cpi` | Consumer Price Index | | `pce` | Personal Consumption Expenditures | | `import-export` | Import & export trade | schema: type: string enum: - gdp - cpi - pce - import-export example: gdp - name: country in: query required: false description: ISO country code. schema: type: string default: JP example: JP - name: period in: query required: false description: Look-back window. schema: type: string enum: - 1Y - 3Y - 10Y default: 10Y responses: '200': description: Selected economic data series. content: application/json: schema: $ref: '#/components/schemas/MacroEconomicDataResponse' example: success: true statusCode: 200 data: - country: JP quarter: Q4 2025 gdp: '672199.300' gdpUnit: Billion JPY growthRate: 0.6 realGdp: null realGrowthRate: null dateFrom: '2025-10-01T00:00:00.000Z' dateTo: '2025-12-31T23:59:59.999Z' - country: JP quarter: Q1 2026 gdp: '677233.400' gdpUnit: Billion JPY growthRate: 0.8 realGdp: null realGrowthRate: null dateFrom: '2026-01-01T00:00:00.000Z' dateTo: '2026-03-31T23:59:59.999Z' meta: timestamp: '2026-06-19T08:50:42.471Z' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' components: schemas: MacroEconomicDataResponse: allOf: - $ref: '#/components/schemas/EnvelopeBase' - type: object required: - data properties: data: type: array description: > Array of observations whose item shape depends on the `type` query parameter: - `gdp` → `EconomicDataPoint` - `cpi` → `MacroCpiData` - `pce` → `MacroPceData` - `import-export` → `MacroImportExportData` items: oneOf: - $ref: '#/components/schemas/EconomicDataPoint' - $ref: '#/components/schemas/MacroCpiData' - $ref: '#/components/schemas/MacroPceData' - $ref: '#/components/schemas/MacroImportExportData' EnvelopeBase: type: object description: > Standard success envelope shared by every endpoint. Each operation's response wrapper extends this (via `allOf`) and adds a typed `data` property. required: - success - statusCode properties: success: type: boolean const: true description: Always `true` for a successful response. example: true statusCode: type: integer description: Mirrors the HTTP status code. example: 200 meta: $ref: '#/components/schemas/Meta' EconomicDataPoint: type: object description: > One observation in an economic data series (GDP / CPI / PCE / import-export). Shared by the GDP growth-rate and economic-data endpoints. required: - country - quarter - gdp - gdpUnit - growthRate - dateFrom - dateTo properties: country: type: string description: ISO country code the series belongs to. example: JP quarter: type: string description: Human-readable observation period. example: Q1 2026 gdp: type: string description: | Nominal value for the period. Delivered as a string on the wire to preserve full numeric precision. example: '677233.400' gdpUnit: type: - string - 'null' description: Unit the value is expressed in. example: Billion JPY growthRate: type: - number - 'null' description: Period-over-period nominal growth rate, in percent. example: 0.8 realGdp: type: - number - 'null' description: Inflation-adjusted value; `null` when not published for the period. example: null realGrowthRate: type: - number - 'null' description: Inflation-adjusted growth rate, in percent; `null` when unavailable. example: null dateFrom: type: string format: date-time description: Inclusive start of the observation period. example: '2026-01-01T00:00:00.000Z' dateTo: type: string format: date-time description: Inclusive end of the observation period. example: '2026-03-31T23:59:59.999Z' MacroCpiData: type: object title: MacroCpiData description: | One CPI (Consumer Price Index) observation. Returned as an item of the economic-data `data` array when the `type` query parameter is `cpi`. required: - id - createdAt - updatedAt - country - observationDate - cpiPoints - coreCpiPoints - cpiChangeYoyPercent - coreCpiChangeYoyPercent properties: id: type: integer description: Unique identifier of the observation record. example: 1024 createdAt: type: string format: date-time description: When the record was created. example: '2026-04-01T08:00:00.000Z' updatedAt: type: string format: date-time description: When the record was last updated. example: '2026-04-01T08:00:00.000Z' country: type: string description: ISO country code the observation belongs to. example: JP observationDate: type: string format: date description: Date of the observation. example: '2026-03-01' cpiPoints: type: - number - 'null' description: Headline CPI index points; `null` when not published for the period. example: 111.2 coreCpiPoints: type: - number - 'null' description: >- Core CPI (excluding food & energy) index points; `null` when unavailable. example: 109.8 cpiChangeYoyPercent: type: - number - 'null' description: >- Year-over-year change in headline CPI, in percent; `null` when unavailable. example: 2.7 coreCpiChangeYoyPercent: type: - number - 'null' description: >- Year-over-year change in core CPI, in percent; `null` when unavailable. example: 2.3 MacroPceData: type: object title: MacroPceData description: > One PCE (Personal Consumption Expenditures) observation. Returned as an item of the economic-data `data` array when the `type` query parameter is `pce`. required: - id - createdAt - updatedAt - country - observationDate - pcePoints - corePcePoints - pceChangeYoyPercent - corePceChangeYoyPercent properties: id: type: integer description: Unique identifier of the observation record. example: 2048 createdAt: type: string format: date-time description: When the record was created. example: '2026-04-01T08:00:00.000Z' updatedAt: type: string format: date-time description: When the record was last updated. example: '2026-04-01T08:00:00.000Z' country: type: string description: ISO country code the observation belongs to. example: US observationDate: type: string format: date description: Date of the observation. example: '2026-03-01' pcePoints: type: - number - 'null' description: Headline PCE index points; `null` when not published for the period. example: 124.5 corePcePoints: type: - number - 'null' description: >- Core PCE (excluding food & energy) index points; `null` when unavailable. example: 122.1 pceChangeYoyPercent: type: - number - 'null' description: >- Year-over-year change in headline PCE, in percent; `null` when unavailable. example: 2.5 corePceChangeYoyPercent: type: - number - 'null' description: >- Year-over-year change in core PCE, in percent; `null` when unavailable. example: 2.2 MacroImportExportData: type: object title: MacroImportExportData description: > One import/export observation. Returned as an item of the economic-data `data` array when the `type` query parameter is `import-export`. Vietnam (`VN`) markets populate turnover values and the trade balance; other markets populate price-index points (PPI/IPI/EPI). Fields not relevant to a market are `null`. required: - id - createdAt - updatedAt - country - observationDate - tradeBalance - importTurnover - exportTurnover - importTurnoverUnits - exportTurnoverUnits - ppiPoints - ipiPoints - epiPoints properties: id: type: integer description: Unique identifier of the observation record. example: 4096 createdAt: type: string format: date-time description: When the record was created. example: '2026-04-01T08:00:00.000Z' updatedAt: type: string format: date-time description: When the record was last updated. example: '2026-04-01T08:00:00.000Z' country: type: string description: ISO country code the observation belongs to. example: VN observationDate: type: string format: date description: Date of the observation. example: '2026-03-01' tradeBalance: type: - number - 'null' description: | Exports minus imports for the period. Populated for `VN`; `null` for markets that report price-index points instead. example: 1200.5 importTurnover: type: - number - 'null' description: Import turnover value; `null` for price-index markets. example: 30500 exportTurnover: type: - number - 'null' description: Export turnover value; `null` for price-index markets. example: 31700.5 importTurnoverUnits: type: - string - 'null' description: >- Unit the import turnover is expressed in; `null` when not applicable. example: Million USD exportTurnoverUnits: type: - string - 'null' description: >- Unit the export turnover is expressed in; `null` when not applicable. example: Million USD ppiPoints: type: - number - 'null' description: Producer Price Index points; `null` for turnover markets. example: null ipiPoints: type: - number - 'null' description: Import Price Index points; `null` for turnover markets. example: null epiPoints: type: - number - 'null' description: Export Price Index points; `null` for turnover markets. example: null ErrorBody: type: object description: Standard error envelope returned for every 4xx / 5xx response. required: - success - statusCode - error properties: success: type: boolean const: false description: Always `false` for an error response. example: false statusCode: type: integer description: Mirrors the HTTP status code. example: 401 error: $ref: '#/components/schemas/ErrorDetail' meta: $ref: '#/components/schemas/Meta' Meta: type: object description: >- Response metadata. Always present; `timestamp` is the server time the response was generated. required: - timestamp properties: timestamp: type: string format: date-time description: Server time when the response was generated (ISO 8601). example: '2026-06-19T08:31:59.478Z' additionalProperties: true ErrorDetail: type: object description: Error detail object carried under `error` in the error envelope. required: - code - message properties: code: type: string description: > Machine-readable error code. Specific for authentication / quota errors (e.g. `API_KEY_REQUIRED`, `API_KEY_INVALID`, `FEATURE_NOT_IN_PLAN`, `RATE_LIMIT_EXCEEDED`). For validation (400) and not-found (404) the code is currently `INTERNAL_ERROR` and the HTTP status carries the semantics. example: API_KEY_INVALID message: description: Human-readable message, or a list of validation messages (400). oneOf: - type: string - type: array items: type: string example: Invalid API key responses: BadRequest: description: >- Invalid or missing parameter — bad enum, range, format, or a missing required query parameter. content: application/json: schema: $ref: '#/components/schemas/ErrorBody' example: success: false statusCode: 400 error: code: INTERNAL_ERROR message: - >- Invalid type parameter. Must be "gdp", "cpi", "pce", or "import-export" - Type parameter is required meta: error: Bad Request statusCode: 400 timestamp: '2026-06-19T08:34:08.081Z' Unauthorized: description: >- Missing, invalid, disabled or expired API key. Send a valid key in the `X-API-Key` header. content: application/json: schema: $ref: '#/components/schemas/ErrorBody' example: success: false statusCode: 401 error: code: API_KEY_INVALID message: Invalid API key meta: timestamp: '2026-06-19T08:34:08.023Z' Forbidden: description: >- Your subscription plan does not include this data feature, or your key's scope denies it. content: application/json: schema: $ref: '#/components/schemas/ErrorBody' example: success: false statusCode: 403 error: code: FEATURE_NOT_IN_PLAN message: Your plan does not include this feature meta: timestamp: '2026-06-19T08:34:08.100Z' RateLimited: description: > Rate limit exceeded — you have consumed your plan's per-minute weight budget. Wait until `X-RateLimit-Reset` (or `Retry-After` seconds) then retry. headers: X-RateLimit-Limit: $ref: '#/components/headers/XRateLimitLimit' X-RateLimit-Remaining: $ref: '#/components/headers/XRateLimitRemaining' X-RateLimit-Reset: $ref: '#/components/headers/XRateLimitReset' X-RateLimit-Weight-Used: $ref: '#/components/headers/XRateLimitWeightUsed' Retry-After: $ref: '#/components/headers/RetryAfter' content: application/json: schema: $ref: '#/components/schemas/ErrorBody' example: success: false statusCode: 429 error: code: RATE_LIMIT_EXCEEDED message: Rate limit exceeded meta: timestamp: '2026-06-19T08:34:09.000Z' InternalError: description: Unexpected server error. Retry after a short exponential backoff. content: application/json: schema: $ref: '#/components/schemas/ErrorBody' example: success: false statusCode: 500 error: code: INTERNAL_ERROR message: Internal server error meta: timestamp: '2026-06-19T08:34:10.000Z' headers: XRateLimitLimit: description: Your plan's request-weight budget per 1-minute window. schema: type: integer example: 1000 XRateLimitRemaining: description: Remaining request weight in the current 1-minute window. schema: type: integer example: 997 XRateLimitReset: description: Unix timestamp (seconds) when the current rate-limit window resets. schema: type: integer format: int64 example: 1781857979 XRateLimitWeightUsed: description: Request weight consumed by this call (see each endpoint's weight). schema: type: integer example: 3 RetryAfter: description: Seconds to wait before retrying. Present on 429 responses. schema: type: integer example: 30 securitySchemes: HayInsightsApiKey: type: apiKey in: header name: X-API-Key description: > Your HayInsights API key (prefixed `apk_`). Create and manage keys in the HayInsights dashboard (Account → API keys). Send it in the `X-API-Key` header on **every** request to `/openapi/v1/*`. Which data domains you may access and your request quota are both governed by the subscription plan attached to the key — see the **Plans & features** and **Rate limits** guides. ````