> ## 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. # Indicator — FDI table (US/JP/VN) > Foreign direct investment for the United States, Japan and Vietnam over the two most recent quarters, oldest to newest. The columns are the two latest quarters with data in either Japan or Vietnam — not anchored to today, because JETRO publishes about two months after the quarter ends. Each cell holds two metrics, `outward` and `inward`, in million USD (the unit is on `rows[].unit`). - **`JP`** (JETRO): outward and inward FDI for the quarter. A negative value is a net withdrawal. - **`VN`** (Foreign Investment Agency, Ministry of Finance): `inward` only — registered capital within the quarter (the three months of that quarter, not year to date). Only complete quarters appear; `outward` is always null. - **`US`**: no source yet — `available: false`, every cell `—`. A country without a figure for a quarter returns a null cell (`display` shows `—`), never 0. `values` holds the raw numbers and `display` the formatted strings. `source` names JETRO, the Japanese source. For longer series use `/macro/fdi/flows` (Japan) or `/macro/fdi/vn/flows` (Vietnam). ## OpenAPI ````yaml /openapi.yaml get /openapi/v1/macro/indicators/fdi 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, trade by region and the manufacturing PMI. - 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 — plus Vietnamese stock (HOSE / HNX / UPCoM) daily prices and financial statements. paths: /openapi/v1/macro/indicators/fdi: get: tags: - Macro summary: Indicator — FDI table (US/JP/VN) description: > Foreign direct investment for the United States, Japan and Vietnam over the two most recent quarters, oldest to newest. The columns are the two latest quarters with data in either Japan or Vietnam — not anchored to today, because JETRO publishes about two months after the quarter ends. Each cell holds two metrics, `outward` and `inward`, in million USD (the unit is on `rows[].unit`). - **`JP`** (JETRO): outward and inward FDI for the quarter. A negative value is a net withdrawal. - **`VN`** (Foreign Investment Agency, Ministry of Finance): `inward` only — registered capital within the quarter (the three months of that quarter, not year to date). Only complete quarters appear; `outward` is always null. - **`US`**: no source yet — `available: false`, every cell `—`. A country without a figure for a quarter returns a null cell (`display` shows `—`), never 0. `values` holds the raw numbers and `display` the formatted strings. `source` names JETRO, the Japanese source. For longer series use `/macro/fdi/flows` (Japan) or `/macro/fdi/vn/flows` (Vietnam). operationId: macroIndicatorFdi parameters: - name: country in: query required: false description: >- Source country of the JETRO series. Only `jp` is accepted; the response always holds the US, JP and VN rows. schema: type: string enum: - jp default: jp - 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: FDI indicator table. content: application/json: schema: $ref: '#/components/schemas/MacroIndicatorFdiResponse' example: success: true statusCode: 200 data: indicator: fdi metrics: - key: outward label: Outward unit: '' - key: inward label: Inward unit: '' columns: - period: Q2 2026 date: '2026-06-30' - period: Q3 2026 date: '2026-09-30' rows: - country: US countryName: United States available: false unit: null values: - null - null display: - outward: — inward: — - outward: — inward: — markers: - {} - {} - country: JP countryName: Japan available: true unit: Million USD values: - outward: 53261.8 inward: 5729.2 - null display: - outward: 53,261.8 inward: 5,729.2 - outward: — inward: — markers: - {} - {} - country: VN countryName: Vietnam available: true unit: Million USD values: - outward: null inward: 19451.5 - outward: null inward: 15707 display: - outward: — inward: 19,451.5 - outward: — inward: 15,707.0 markers: - {} - {} latestPeriod: 2026-Q3 source: JETRO knowledgeAt: '2026-09-10T00:00:00.000Z' wasRestated: false meta: timestamp: '2026-10-16T04:00:00.000Z' '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: MacroIndicatorFdiResponse: allOf: - $ref: '#/components/schemas/EnvelopeBase' - type: object required: - data properties: data: type: object required: - indicator - metrics - columns - rows - source properties: indicator: type: string description: Table identifier. example: fdi metrics: type: array items: type: object required: - key - label - unit properties: key: type: string description: Metric key. enum: - outward - inward example: outward label: type: string description: Display label. example: Outward unit: type: string description: Always empty — the unit is on `rows[].unit`. example: '' columns: type: array items: type: object required: - period - date properties: period: type: string description: Quarter label. example: Q3 2026 date: type: string description: Last day of the quarter. format: date example: '2026-09-30' description: >- The two latest quarters with data in Japan or Vietnam, oldest to newest. rows: type: array items: type: object required: - country - countryName - available - values properties: country: type: string description: Country code. Always three rows, in this order. enum: - US - JP - VN example: VN countryName: type: string description: Country name. example: Japan available: type: boolean description: >- False when the country has no figure in any column (the US for now). example: true unit: type: - string - 'null' description: Unit of the row; null when `available` is false. example: Million USD values: type: array items: type: - object - 'null' additionalProperties: type: - number - 'null' description: > One cell per column, keyed by metric (`outward`, `inward`). A cell is null when the country has no figure for that quarter. Vietnam's `outward` is always null. display: type: array items: type: object additionalProperties: type: string markers: type: array items: type: object additionalProperties: type: string latestPeriod: type: - string - 'null' description: Latest quarter in the table (`YYYY-Qn`). example: 2026-Q3 source: type: string description: >- Publisher of the Japanese series. The Vietnam row comes from the Foreign Investment Agency. example: JETRO knowledgeAt: type: - string - 'null' description: When the system learned the figures. wasRestated: type: boolean example: false 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.