> ## 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. # Vietnam CPI by component (NSO) > Vietnam's consumer price index by group of goods and services, quarterly, from the National Statistics Office of Viet Nam (NSO). Every value is the **quarterly average against the average of the same quarter of the previous year, in %** — so a chain of quarters is comparable even though NSO has changed the index base year several times. `components` lists the 19 lines in the order NSO prints them, and `points` has one entry per quarter, oldest first, from `2015-Q1` to the latest complete quarter. A quarter still in progress has no point yet; `latestMonth` says how far the monthly data has reached. | Code | `level` | Line | | --- | --- | --- | | `cpi_total` | 0 | Headline CPI | | `food_catering`, `beverages_tobacco`, `garments_footwear`, `housing_utilities`, `household_equipment`, `medicine_health`, `transport`, `communication`, `education`, `culture_entertainment_tourism`, `other_goods_services` | 1 | The 11 groups | | `staple_food`, `foodstuff`, `eating_out` (under `food_catering`), `health_services` (under `medicine_health`), `education_services` (under `education`) | 2 | The 5 sub-groups | | `gold_price_index`, `usd_price_index` | 0 | Gold and US dollar price indices | **Printed and computed quarters.** `values[code].classification` is `RAW` when NSO prints the quarterly average (the March, June, September and December tables of 2019 and 2026). Otherwise it is `COMPUTED` by HayInsights from the three months of the quarter, with the monthly index and the monthly change against the same month of the previous year (`meta.formula_version`). Computed values can differ from what NSO would print by a few hundredths of a point, and by up to 0.18 for the most volatile groups, because NSO works from unrounded indices. **Missing data.** `values[code]` is `null` — never 0 — when a quarter does not have all three months for that code. `eating_out`, `health_services` and `education_services` are mostly unavailable before 2021. Pass `asOf` to get the series as it was known at the end of a past day (point-in-time, for backtests). If nothing was known yet, `points` is empty and `latestQuarter` and `latestMonth` are `null`. Source: National Statistics Office of Viet Nam ([www.nso.gov.vn](https://www.nso.gov.vn)). Cite the source when you republish these numbers. ## OpenAPI ````yaml /openapi.yaml get /openapi/v1/macro/vietnam/cpi-by-component 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/vietnam/cpi-by-component: get: tags: - Macro summary: Vietnam CPI by component (NSO) description: > Vietnam's consumer price index by group of goods and services, quarterly, from the National Statistics Office of Viet Nam (NSO). Every value is the **quarterly average against the average of the same quarter of the previous year, in %** — so a chain of quarters is comparable even though NSO has changed the index base year several times. `components` lists the 19 lines in the order NSO prints them, and `points` has one entry per quarter, oldest first, from `2015-Q1` to the latest complete quarter. A quarter still in progress has no point yet; `latestMonth` says how far the monthly data has reached. | Code | `level` | Line | | --- | --- | --- | | `cpi_total` | 0 | Headline CPI | | `food_catering`, `beverages_tobacco`, `garments_footwear`, `housing_utilities`, `household_equipment`, `medicine_health`, `transport`, `communication`, `education`, `culture_entertainment_tourism`, `other_goods_services` | 1 | The 11 groups | | `staple_food`, `foodstuff`, `eating_out` (under `food_catering`), `health_services` (under `medicine_health`), `education_services` (under `education`) | 2 | The 5 sub-groups | | `gold_price_index`, `usd_price_index` | 0 | Gold and US dollar price indices | **Printed and computed quarters.** `values[code].classification` is `RAW` when NSO prints the quarterly average (the March, June, September and December tables of 2019 and 2026). Otherwise it is `COMPUTED` by HayInsights from the three months of the quarter, with the monthly index and the monthly change against the same month of the previous year (`meta.formula_version`). Computed values can differ from what NSO would print by a few hundredths of a point, and by up to 0.18 for the most volatile groups, because NSO works from unrounded indices. **Missing data.** `values[code]` is `null` — never 0 — when a quarter does not have all three months for that code. `eating_out`, `health_services` and `education_services` are mostly unavailable before 2021. Pass `asOf` to get the series as it was known at the end of a past day (point-in-time, for backtests). If nothing was known yet, `points` is empty and `latestQuarter` and `latestMonth` are `null`. Source: National Statistics Office of Viet Nam ([www.nso.gov.vn](https://www.nso.gov.vn)). Cite the source when you republish these numbers. operationId: macroVietnamCpiByComponent parameters: - name: asOf in: query required: false description: > Point-in-time date (`YYYY-MM-DD`): return only what was known by the end of that day (UTC), leaving out data and revisions published later. Omit for the latest data. schema: type: string format: date example: '2026-10-01' responses: '200': description: > Quarterly CPI by component. The example shows 5 of the 19 components and the first and the last of the 47 quarters. content: application/json: schema: $ref: '#/components/schemas/MacroVietnamCpiByComponentResponse' example: success: true statusCode: 200 data: country: vn measure: quarter_avg_yoy unit: PERCENT components: - code: cpi_total level: 0 parent: null nameVi: Chỉ số giá tiêu dùng nameEn: All items (CPI) - code: food_catering level: 1 parent: cpi_total nameVi: Hàng ăn và dịch vụ ăn uống nameEn: Food and catering services - code: eating_out level: 2 parent: food_catering nameVi: Ăn uống ngoài gia đình nameEn: Eating out - code: gold_price_index level: 0 parent: null nameVi: Chỉ số giá vàng nameEn: Gold price index - code: usd_price_index level: 0 parent: null nameVi: Chỉ số giá đô la Mỹ nameEn: US dollar price index points: - quarter: 2015-Q1 startDate: '2015-01-01' values: cpi_total: value: 0.74 classification: COMPUTED food_catering: value: 2.14 classification: COMPUTED eating_out: null gold_price_index: value: -2.49 classification: COMPUTED usd_price_index: value: 1.26 classification: COMPUTED - quarter: 2026-Q3 startDate: '2026-07-01' values: cpi_total: value: 4.8 classification: RAW food_catering: value: 4.58 classification: RAW eating_out: value: 7.72 classification: RAW gold_price_index: value: 16.15 classification: RAW usd_price_index: value: -0.45 classification: RAW latestQuarter: 2026-Q3 latestMonth: 2026-09 source: Cục Thống kê (NSO) — www.nso.gov.vn wasRestated: false meta: source: Cục Thống kê (NSO) — www.nso.gov.vn as_of: 2026-09 unit: PERCENT classification: value: >- RAW when NSO prints the quarterly average (March, June, September, December tables of 2019 and 2026), COMPUTED from the three months otherwise formula_version: cpi-quarter-avg-from-months-v1 was_restated: false served_from_cache: true cache_expires_at: '2026-11-07T01:12:40.000Z' timestamp: '2026-11-06T03:00:00.000Z' '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: MacroVietnamCpiByComponentResponse: allOf: - $ref: '#/components/schemas/EnvelopeBase' - type: object required: - data properties: data: $ref: '#/components/schemas/CpiByComponentSeries' meta: $ref: '#/components/schemas/CpiByComponentMeta' 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' CpiByComponentSeries: type: object description: Vietnam CPI by component, one point per quarter. required: - country - measure - unit - components - points - latestQuarter - latestMonth - source - wasRestated properties: country: type: string enum: - vn description: Country. Only Vietnam for now. example: vn measure: type: string enum: - quarter_avg_yoy description: >- Every value is the quarterly average against the average of the same quarter of the previous year. example: quarter_avg_yoy unit: type: string enum: - PERCENT description: Unit of `value`. example: PERCENT components: type: array description: The lines of the series, in the order NSO prints them. items: $ref: '#/components/schemas/CpiComponent' points: type: array description: >- One entry per quarter, oldest first. Empty if nothing was known at `asOf`. items: $ref: '#/components/schemas/CpiQuarterPoint' latestQuarter: type: - string - 'null' description: Latest complete quarter with data (`YYYY-Qn`). example: 2026-Q3 latestMonth: type: - string - 'null' description: Latest month with data (`YYYY-MM`). Can be ahead of `latestQuarter`. example: 2026-09 source: type: string description: Data provider. example: Cục Thống kê (NSO) — www.nso.gov.vn wasRestated: type: boolean description: >- NSO has revised a published number in this series since its first release. example: false CpiByComponentMeta: description: > Response metadata for CPI by component. On top of `timestamp`, it says where the numbers came from, how they were produced, and how fresh the response is. allOf: - $ref: '#/components/schemas/Meta' - type: object properties: source: type: string description: Data provider. example: Cục Thống kê (NSO) — www.nso.gov.vn as_of: type: - string - 'null' description: Latest month with data (`YYYY-MM`); same as `data.latestMonth`. example: 2026-09 unit: type: string description: Unit of `value`. example: PERCENT classification: type: object description: >- How `value` is produced. Each value also says it in `values[code].classification`. properties: value: type: string example: >- RAW when NSO prints the quarterly average (March, June, September, December tables of 2019 and 2026), COMPUTED from the three months otherwise formula_version: type: string description: Version tag of the formula behind `COMPUTED` values. example: cpi-quarter-avg-from-months-v1 was_restated: type: boolean description: Same as `data.wasRestated`. example: false served_from_cache: type: boolean description: Whether the response was served from cache. example: true cache_expires_at: type: - string - 'null' format: date-time description: >- When the cached copy expires (24 h; it is dropped as soon as new data is collected). example: '2026-11-07T01:12:40.000Z' 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 CpiComponent: type: object description: One line of the NSO CPI table. required: - code - level - parent - nameVi - nameEn properties: code: type: string description: >- Stable code of the line; the key of `values` in `points`. It does not change when NSO renames a line. example: food_catering level: type: integer enum: - 0 - 1 - 2 description: >- `0` headline CPI and the gold and USD price indices, `1` group, `2` sub-group. example: 1 parent: type: - string - 'null' description: >- Code of the parent line. Groups sit under `cpi_total`; `null` for `cpi_total` and the gold and USD price indices. example: cpi_total nameVi: type: string description: Name in Vietnamese. example: Hàng ăn và dịch vụ ăn uống nameEn: type: string description: Name in English. example: Food and catering services CpiQuarterPoint: type: object description: One quarter of the series. required: - quarter - startDate - values properties: quarter: type: string description: Quarter (`YYYY-Qn`). example: 2026-Q3 startDate: type: string format: date description: First day of the quarter. example: '2026-07-01' values: type: object description: >- Value per component `code`. `null` when the quarter does not have all three months for that code. additionalProperties: $ref: '#/components/schemas/CpiQuarterValue' 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 CpiQuarterValue: type: - object - 'null' description: One value of the series, or `null` when it is missing. required: - value - classification properties: value: type: number description: >- Quarterly average against the same quarter of the previous year, in %, to 2 decimals. example: 4.8 classification: type: string enum: - RAW - COMPUTED description: >- `RAW` as printed by NSO, `COMPUTED` by HayInsights from the three months of the quarter. example: RAW 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. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.