> ## 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. # Export/import by region > Exports or imports of one country split by region for one period. There is always an item for the part not attributed to any region, so the items add up to `total`. Each item has a `classification`: RAW is published by the source, DERIVED is computed. Pick the period with `granularity` (latest month / quarter / year) or name it with `period`; `period` wins when both are given. Returns 404 when no data has been collected for the country yet. ## OpenAPI ````yaml /openapi.yaml get /openapi/v1/macro/trade/by-region 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, real-estate, news, economic-calendar and market-index 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-v2.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, fund composition and Bank of Japan ETF holdings. - 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, policy rates / bond yields, interbank rates, FDI and trade by region. - name: Real Estate description: >- Land prices, transaction-level records, administrative geography (provinces / wards) and choropleth GeoJSON, by country. - name: News description: >- Market news headlines with per-article sentiment, plus an aggregate sentiment reading over a rolling window. - name: Calendar description: >- Economic calendar — rate decisions, CPI and GDP releases, market holidays and asset-level events. - name: Market description: >- Index snapshots and global index closes — levels and daily moves for S&P 500, Nasdaq, Nikkei, VN-Index and others. - name: Equities description: >- Japanese stock detail (Tokyo Stock Exchange) — end-of-day snapshot, corporate events, daily prices, financial statements and sector peers. paths: /openapi/v1/macro/trade/by-region: get: tags: - Macro summary: Export/import by region description: > Exports or imports of one country split by region for one period. There is always an item for the part not attributed to any region, so the items add up to `total`. Each item has a `classification`: RAW is published by the source, DERIVED is computed. Pick the period with `granularity` (latest month / quarter / year) or name it with `period`; `period` wins when both are given. Returns 404 when no data has been collected for the country yet. operationId: macroTradeByRegion parameters: - name: country in: query required: true description: Country. schema: type: string enum: - jp - vn - us example: jp - name: flow in: query required: false description: Trade flow. schema: type: string enum: - export - import default: export - name: granularity in: query required: false description: Use the latest period of this granularity. schema: type: string enum: - month - quarter - year - fiscal_year default: month - name: period in: query required: false description: 'Exact period: `2026-06`, `2026-Q2`, `2026` or `2026-FY`.' schema: type: string pattern: ^\d{4}(-(0[1-9]|1[0-2])|-Q[1-4]|-FY)?$ example: 2026-Q2 - name: taxonomy in: query required: false description: >- Region grouping. Defaults to continents for Japan and Vietnam and Census regions for the US. schema: type: string enum: - source - continent - name: asOf in: query required: false description: >- Backtest: return exactly what the system knew at the end of that day (UTC), not later revisions by the source. Omit for the latest data. schema: type: string format: date example: '2026-09-01' responses: '200': description: Trade split by region. content: application/json: schema: $ref: '#/components/schemas/MacroTradeByRegionResponse' example: success: true statusCode: 200 data: country: jp unit: JPY unitScale: 1000 displayDivisor: 1000000 displayUnit: Billion Yen seasonallyAdjusted: false source: Ministry of Finance Japan taxonomy: continent asOfPeriod: 2026-08 period: 2026-Q2 granularity: quarter flow: export isPartial: false total: 25321000000 items: - code: asia name: Asia value: 14990000000 share: 0.592 classification: RAW - code: north_america name: North America value: 5621000000 share: 0.222 classification: RAW reconciliation: sumOfItems: 25321000000 total: 25321000000 diff: 0 meta: timestamp: '2026-10-16T04:00:00.000Z' source: Ministry of Finance Japan as_of: 2026-Q2 '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' components: schemas: MacroTradeByRegionResponse: allOf: - $ref: '#/components/schemas/EnvelopeBase' - type: object required: - data properties: data: type: object required: - country - displayUnit - source - period - flow - total - items properties: country: type: string description: Country code. example: jp unit: type: string description: Storage unit. example: JPY unitScale: type: number example: 1000 displayDivisor: type: number description: Divide values by this to get `displayUnit`. example: 1000000 displayUnit: type: string description: Display unit. example: Billion Yen seasonallyAdjusted: type: boolean example: false source: type: string description: Publisher. example: Ministry of Finance Japan taxonomy: type: string description: Region grouping. enum: - source - continent example: continent asOfPeriod: type: string description: Latest period with data. example: 2026-08 period: type: string description: Period served. example: 2026-Q2 granularity: type: string description: Granularity served. example: quarter flow: type: string description: Flow served. enum: - export - import example: export isPartial: type: boolean example: false coverage: type: string description: Months covered by a partial period. total: type: number example: 25321000000 items: type: array items: type: object required: - code - name - value - share - classification properties: code: type: string description: Region code. example: asia name: type: string description: Region name. example: Asia value: type: number example: 14990000000 share: type: number description: Share of `total` (0–1). example: 0.592 classification: type: string description: RAW or DERIVED. enum: - RAW - DERIVED example: RAW note: type: string description: Note on the item. valueMarker: type: string description: Source marker on the value. reconciliation: type: object description: Check that the items add up to the total. properties: sumOfItems: type: number total: type: number diff: type: number excluded: type: number 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' 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' NotFound: description: The requested resource was not found. content: application/json: schema: $ref: '#/components/schemas/ErrorBody' example: success: false statusCode: 404 error: code: INTERNAL_ERROR message: Commodity 'zzz-nope' not found meta: error: Not Found statusCode: 404 timestamp: '2026-06-19T08:34:08.205Z' 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. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.