{ "basePath": "/api/v1", "definitions": { "ArmidDataCategory": { "properties": { "children": { "items": { "$ref": "#/definitions/ArmidDataCategory" }, "type": "array" }, "id": { "type": "string" }, "name": { "description": "Name is the category's display name.", "type": "string" }, "seriesCount": { "description": "SeriesCount is how many time series with data sit in this category or\nany category under it, each counted once.", "type": "integer" } }, "type": "object" }, "ArmidDataCategoryDetail": { "properties": { "children": { "description": "Children are the categories directly under this one, without their\nown children.", "items": { "$ref": "#/definitions/ArmidDataCategory" }, "type": "array" }, "id": { "type": "string" }, "name": { "type": "string" }, "path": { "description": "Path is the categories above this one, top-level first.", "items": { "$ref": "#/definitions/ArmidDataCategoryRef" }, "type": "array" }, "seriesCount": { "type": "integer" } }, "type": "object" }, "ArmidDataCategoryList": { "properties": { "categories": { "items": { "$ref": "#/definitions/ArmidDataCategory" }, "type": "array" } }, "type": "object" }, "ArmidDataCategoryMatch": { "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "path": { "items": { "$ref": "#/definitions/ArmidDataCategoryRef" }, "type": "array" }, "seriesCount": { "type": "integer" } }, "type": "object" }, "ArmidDataCategoryMatches": { "properties": { "categories": { "items": { "$ref": "#/definitions/ArmidDataCategoryMatch" }, "type": "array" } }, "type": "object" }, "ArmidDataCategoryRef": { "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "ArmidDataCountry": { "properties": { "code": { "type": "string" }, "name": { "type": "string" } }, "type": "object" }, "ArmidDataObservation": { "properties": { "date": { "type": "string" }, "dimensions": { "additionalProperties": {}, "description": "Dimensions tell apart several observations of the same date, e.g. a\nbreakdown by sex or age.", "type": "object" }, "location": { "$ref": "#/definitions/ArmidDataPoint" }, "metrics": { "additionalProperties": {}, "description": "Metrics are several named values recorded together for the date.", "type": "object" }, "period": { "description": "Period is Date written for the series' frequency (see\nArmidDataSeries.LastPeriod).", "type": "string" }, "text": { "description": "Text is set for a text-valued observation.", "type": "string" }, "value": { "type": "number" } }, "type": "object" }, "ArmidDataObservations": { "properties": { "observations": { "items": { "$ref": "#/definitions/ArmidDataObservation" }, "type": "array" }, "returned": { "description": "Returned is len(Observations); Total is how many match start/end.", "type": "integer" }, "series": { "$ref": "#/definitions/ArmidDataSeries" }, "total": { "type": "integer" }, "truncated": { "description": "Truncated is true when only the newest Returned of Total are here.", "type": "boolean" } }, "type": "object" }, "ArmidDataPoint": { "properties": { "coordinates": { "items": { "type": "number" }, "type": "array" }, "type": { "example": "Point", "type": "string" } }, "type": "object" }, "ArmidDataSeries": { "properties": { "categories": { "description": "Categories are the categories the series belongs to (single-series\nresponses only).", "items": { "$ref": "#/definitions/ArmidDataCategoryRef" }, "type": "array" }, "country": { "allOf": [ { "$ref": "#/definitions/ArmidDataCountry" } ], "description": "Country is the country the series is about." }, "firstDate": { "type": "string" }, "frequency": { "description": "Frequency is the spacing of the observations: hourly, daily, weekly,\ndekadal, monthly, quarterly, semiannual, annual, irregular, or unknown\nwhen there are too few to tell.", "enum": [ "hourly", "daily", "weekly", "dekadal", "monthly", "quarterly", "semiannual", "annual", "irregular", "unknown" ], "type": "string" }, "geometry": { "description": "Geometry is \"point\" when each observation carries its own location\n(e.g. an earthquake), otherwise \"none\".", "enum": [ "none", "point", "polygon" ], "type": "string" }, "id": { "description": "ID is the series key, FREQ.REF_AREA.INDICATOR, the same as the first\nthree dimensions of the series in the SDMX API. It never changes.", "example": "M.AM.IHB2Q7K3MZ4XA", "type": "string" }, "lastCollectedAt": { "description": "LastCollectedAt is when ARMID last checked the series for new data.", "type": "string" }, "lastDate": { "type": "string" }, "lastPeriod": { "description": "LastPeriod is LastDate written for the frequency: \"2024\" (annual),\n\"2024-Q1\", \"2024-03\", \"2024-03-15\", or a full timestamp when the time\nof day matters.", "type": "string" }, "lastValue": { "description": "LastValue is the newest observation's value; LastValueText is set\ninstead for a text-valued series.", "type": "number" }, "lastValueText": { "type": "string" }, "name": { "type": "string" }, "place": { "description": "Place is the region or city within the country, when the series is\nabout one.", "type": "string" }, "unit": { "type": "string" } }, "type": "object" }, "ArmidDataSeriesPage": { "properties": { "items": { "items": { "$ref": "#/definitions/ArmidDataSeries" }, "type": "array" }, "page": { "type": "integer" }, "pageSize": { "type": "integer" }, "totalItems": { "type": "integer" }, "totalPages": { "type": "integer" } }, "type": "object" }, "errorResponse": { "properties": { "error": { "type": "string" } }, "type": "object" } }, "host": "", "info": { "contact": { "email": "info@ridgital.com", "name": "Ridgital", "url": "https://ridgital.com" }, "description": "---\n\nThe ARMID data API gives read-only access to Armenia In Data: tens of thousands of time series on Armenia - economy, trade, agriculture, finance, climate, energy, population and more - organized in ARMID's own category tree. Browse the categories, list the time series in one, and download any series' observations as JSON, CSV or GeoJSON - or read the same data through the standard [SDMX 2.1](https://sdmx.org) API, with any SDMX client. It is the same data the **Data** tab of ARMID Explorer shows.\n\n---\n\n# Getting Started\n\n1. [Request ARMID Explorer access](https://ridgital.com/armenia-in-data). The data API needs the **Data** section in your access, which runs until a set date.\n2. Sign in to the Ridgital dashboard and create an API key under **Account → API Keys** (members with the editor or admin role can create keys).\n3. Send the key with every request.\n\nAn API key works for as long as your organization's ARMID Explorer access is active. When the access expires, requests return **403** until it is extended.\n\n# Authentication\n\n```http\nAuthorization: Bearer rdg_\u003cyour_api_key\u003e\n```\n\n| Status | `code` | Meaning |\n|--------|--------|---------|\n| 401 | `authentication_required` | No `Authorization: Bearer` header was sent. |\n| 401 | `missing_api_key`, `invalid_api_key`, `api_key_disabled`, `api_key_revoked`, `api_key_expired` | The key is empty or not usable. |\n| 403 | `armid_access_required` | Your organization has no ARMID Explorer access. |\n| 403 | `armid_access_expired` | Your organization's ARMID Explorer access has ended. |\n| 403 | `armid_section_not_granted` | Your access does not include the Data section. |\n\n# Base URL\n\n```text\nhttps://ridgital.com/api/v1/armid/data\n```\n\n# Quick start\n\n```bash\n# 1. The category tree\ncurl -H \"Authorization: Bearer $KEY\" https://ridgital.com/api/v1/armid/data/categories\n\n# 2. Find a category\ncurl -H \"Authorization: Bearer $KEY\" \"https://ridgital.com/api/v1/armid/data/categories/search?q=inflation\"\n\n# 3. The time series in it\ncurl -H \"Authorization: Bearer $KEY\" \"https://ridgital.com/api/v1/armid/data/categories/{id}/series?pageSize=50\"\n\n# 4. A series' observations, as CSV ({id} is the series key from step 3, e.g. M.AM.IHB2Q7K3MZ4XA)\ncurl -H \"Authorization: Bearer $KEY\" \"https://ridgital.com/api/v1/armid/data/series/{id}/observations?limit=all\u0026format=csv\" -o series.csv\n```\n\n# Conventions\n\n- **Series keys**: a time series' `id` is its key, `FREQ.REF_AREA.INDICATOR` (e.g. `M.AM.IHB2Q7K3MZ4XA`: monthly, Armenia, one indicator). A key never changes and is never reused, so it is safe to store. It is also the first part of the series' key in the SDMX API.\n- **Categories** form a tree: top-level categories, each with subcategories. A category's time series include those of every category under it, and a series can sit in more than one category.\n- **Lists are paged**: `page` (from 1) and `pageSize` (up to 100). A page is `{\"items\": [...], \"page\", \"pageSize\", \"totalItems\", \"totalPages\"}`.\n- **Dates** are UTC, RFC 3339. Each observation also has a `period` written for the series' frequency: `2024` (annual), `2024-H1`, `2024-Q1`, `2024-03` (monthly), `2024-03-15` (daily, weekly, dekadal), or for other frequencies the date, with the time of day when it has one.\n- **Frequency** is one of `hourly`, `daily`, `weekly`, `dekadal` (10-day), `monthly`, `quarterly`, `semiannual`, `annual`, `irregular` (e.g. events such as earthquakes) or `unknown` (too few observations to tell).\n- **Observations** are returned oldest first. By default you get the newest 1,000; pass `limit` (a number, or `all` for up to 200,000) and `start`/`end` to choose. `truncated` tells you whether older ones were left out; every format, CSV and GeoJSON included, also sends it as the `X-Truncated` header, with `X-Total-Count` (observations in the chosen period) and `X-Returned-Count`. When a file is truncated, narrow `start`/`end` and fetch the rest in parts.\n- **Values**: `value` is a number (`null` when the observation only has a text or metrics). `dimensions` tell apart several observations of the same date (a breakdown by sex, age, partner country, …); `metrics` are several named values recorded together; `location` is a GeoJSON point for observations that have their own place.\n- **Formats**: `format=json` (default), `format=csv` (one column per dimension and metric) or `format=geojson` (a FeatureCollection of the observations that have a location).\n- **Errors** are `{\"error\": \"message\", \"code\": \"machine_readable_code\"}`.\n\n# SDMX\n\nEvery category with data is also an SDMX dataflow, so any SDMX 2.1 client - `sdmx1`/`pandasdmx` in Python, `rsdmx` in R, .Stat, the SDMX Excel add-ins - can browse and download ARMID. The base URL is `https://ridgital.com/api/v1/armid/sdmx`, with the same API key.\n\n| Query | Returns |\n|-------|---------|\n| `GET /dataflow` | Every dataflow: `DF_` and the category, e.g. `DF_FOOD_MARKET_PRICES`. |\n| `GET /categoryscheme/RIDGITAL/ARMID_TOPICS/latest?references=parentsandsiblings` | The category tree, with each dataflow filed under its category. |\n| `GET /datastructure/RIDGITAL/DSD_ARMID/latest?references=children` | The data structure, its concepts and codelists (`CL_FREQ`, `CL_AREA`). |\n| `GET /data/DF_FOOD_MARKET_PRICES/M.AM...?startPeriod=2024-01` | Observations. |\n\nStructures are SDMX-ML 2.1. Data is SDMX-ML 2.1 Generic by default; add `format=jsondata` for SDMX-JSON 1.0 or `format=csvdata` for SDMX-CSV 1.0 (or send the matching `Accept` header).\n\n**Series key**: `FREQ.REF_AREA.INDICATOR.BREAKDOWN.MEASURE`. The first three are the series key of the data API. `BREAKDOWN` tells apart the values a series breaks down by sex, age, partner country and so on (`_Z` when it does not; the series attribute `BREAKDOWN_LABEL` says what a code stands for) - for located events such as fire detections, each location is its own breakdown, so simultaneous events at different places all come through, and `MEASURE` the several values some series record per date, such as daily climate variables (`_Z` for the series' own value). Leave a dimension empty for every value, join several with `+`, or use `all` for the whole dataflow.\n\n**Parameters**: `startPeriod`/`endPeriod` (`2024`, `2024-S1`, `2024-Q1`, `2024-01`, `2024-01-15`), `firstNObservations`/`lastNObservations`, and `detail` (`full`, `dataonly`, `serieskeysonly`, `nodata`). A response holds at most 200,000 observations; a larger query answers **413** - narrow the key or the period.\n\n**Frequencies** (`CL_FREQ`): `A` annual, `S` half-yearly, `Q` quarterly, `M` monthly, `W` weekly, `D10` dekadal, `D` daily, `H` hourly, `I` irregular (events such as earthquakes, with the time of day in `TIME_PERIOD`), `U` undetermined.\n\n```python\nimport io, pandas as pd, requests\n\nr = requests.get(\n \"https://ridgital.com/api/v1/armid/sdmx/data/DF_FOOD_MARKET_PRICES/M.AM...\",\n params={\"format\": \"csvdata\", \"startPeriod\": \"2024-01\"},\n headers={\"Authorization\": \"Bearer rdg_\u003cyour_api_key\u003e\"},\n)\ndf = pd.read_csv(io.StringIO(r.text)) # one row per observation\n```\n", "title": "Ridgital ARMID Explorer API", "version": "1.0", "x-logo": { "altText": "Ridgital", "href": "/", "url": "/logo.png" } }, "paths": { "/armid/data/categories": { "get": { "description": "Every category with data, top-level categories first, each with\nits subcategories. seriesCount counts the time series with data in\na category and everything under it, each series once.", "produces": [ "application/json" ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/ArmidDataCategoryList" } } }, "security": [ { "ArmidAPIKey": [] }, { "CookieAuth": [] } ], "summary": "Category tree", "tags": [ "Categories" ] } }, "/armid/data/categories/search": { "get": { "description": "Categories whose name contains every word of q (case-insensitive),\neach with its path from the top-level category.", "parameters": [ { "description": "Search words, at least 2 characters", "in": "query", "name": "q", "required": true, "type": "string" } ], "produces": [ "application/json" ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/ArmidDataCategoryMatches" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/errorResponse" } } }, "security": [ { "ArmidAPIKey": [] }, { "CookieAuth": [] } ], "summary": "Search categories", "tags": [ "Categories" ] } }, "/armid/data/categories/{id}": { "get": { "description": "A category with its path from the top-level category and the\ncategories directly under it.", "parameters": [ { "description": "Category id", "in": "path", "name": "id", "required": true, "type": "string" } ], "produces": [ "application/json" ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/ArmidDataCategoryDetail" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/errorResponse" } } }, "security": [ { "ArmidAPIKey": [] }, { "CookieAuth": [] } ], "summary": "One category", "tags": [ "Categories" ] } }, "/armid/data/categories/{id}/series": { "get": { "description": "The time series with data in a category and every category under\nit, by name. q narrows them to names containing every word of it.", "parameters": [ { "description": "Category id", "in": "path", "name": "id", "required": true, "type": "string" }, { "description": "Search words", "in": "query", "name": "q", "type": "string" }, { "default": 1, "description": "Page, from 1", "in": "query", "name": "page", "type": "integer" }, { "default": 20, "description": "Series per page, ≤ 100", "in": "query", "name": "pageSize", "type": "integer" } ], "produces": [ "application/json" ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/ArmidDataSeriesPage" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/errorResponse" } } }, "security": [ { "ArmidAPIKey": [] }, { "CookieAuth": [] } ], "summary": "Time series in a category", "tags": [ "Time series" ] } }, "/armid/data/series/{id}": { "get": { "description": "A time series' description, its newest value and the categories it\nbelongs to.", "parameters": [ { "description": "Series key", "in": "path", "name": "id", "required": true, "type": "string" } ], "produces": [ "application/json" ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/ArmidDataSeries" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/errorResponse" } } }, "security": [ { "ArmidAPIKey": [] }, { "CookieAuth": [] } ], "summary": "One time series", "tags": [ "Time series" ] } }, "/armid/data/series/{id}/observations": { "get": { "description": "The newest observations of a series (1,000 by default, limit=all for\nevery one, at most 200,000), returned oldest first. format=csv returns\na CSV file with one column per dimension and metric; format=geojson\nreturns a GeoJSON FeatureCollection of the observations that have a\nlocation. Every format carries X-Total-Count (observations matching\nstart/end), X-Returned-Count and X-Truncated (true when the limit\ncut the answer short) headers; JSON also has them in the body.", "parameters": [ { "description": "Series key", "in": "path", "name": "id", "required": true, "type": "string" }, { "default": "1000", "description": "How many of the newest observations: a number or all", "in": "query", "name": "limit", "type": "string" }, { "description": "Earliest date, YYYY-MM-DD or RFC 3339", "in": "query", "name": "start", "type": "string" }, { "description": "Latest date, YYYY-MM-DD or RFC 3339", "in": "query", "name": "end", "type": "string" }, { "default": "json", "description": "json, csv or geojson", "in": "query", "name": "format", "type": "string" } ], "produces": [ "application/json", "text/csv", "application/geo+json" ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/ArmidDataObservations" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/errorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/errorResponse" } } }, "security": [ { "ArmidAPIKey": [] }, { "CookieAuth": [] } ], "summary": "Observations of a time series", "tags": [ "Observations" ] } }, "/armid/sdmx/data/{flowRef}/{key}": { "get": { "description": "An SDMX 2.1 data query on one dataflow. key is FREQ.REF_AREA.\nINDICATOR.BREAKDOWN.MEASURE: leave a dimension empty for every value,\njoin several with +, or use all. The response is SDMX-ML 2.1 Generic\ndata by default; format=jsondata or format=csvdata (or the matching\nAccept header) return SDMX-JSON 1.0 or SDMX-CSV 1.0. At most 200,000\nobservations per response.", "parameters": [ { "description": "Dataflow: DF_ID, RIDGITAL,DF_ID or RIDGITAL,DF_ID,1.0", "in": "path", "name": "flowRef", "required": true, "type": "string" }, { "description": "Series key, or all", "in": "path", "name": "key", "required": true, "type": "string" }, { "description": "Earliest period: 2020, 2020-S1, 2020-Q1, 2020-01 or 2020-01-15", "in": "query", "name": "startPeriod", "type": "string" }, { "description": "Latest period, same forms", "in": "query", "name": "endPeriod", "type": "string" }, { "description": "Only the first n observations of each series", "in": "query", "name": "firstNObservations", "type": "integer" }, { "description": "Only the last n observations of each series", "in": "query", "name": "lastNObservations", "type": "integer" }, { "default": "full", "description": "full, dataonly, serieskeysonly or nodata", "in": "query", "name": "detail", "type": "string" }, { "default": "genericdata", "description": "genericdata, jsondata or csvdata", "in": "query", "name": "format", "type": "string" } ], "produces": [ "text/xml", "application/json", "text/csv" ], "responses": { "200": { "description": "SDMX data message", "schema": { "type": "string" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/errorResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/errorResponse" } }, "413": { "description": "Request Entity Too Large", "schema": { "$ref": "#/definitions/errorResponse" } } }, "security": [ { "ArmidAPIKey": [] }, { "CookieAuth": [] } ], "summary": "SDMX data", "tags": [ "SDMX data" ] } }, "/armid/sdmx/{resource}/{agencyID}/{resourceID}/{version}": { "get": { "description": "An SDMX 2.1 structure query, answered in SDMX-ML 2.1: dataflow,\ndatastructure, codelist, conceptscheme, categoryscheme or\ncategorisation. agencyID is RIDGITAL or all, resourceID an id or\nall, version 1.0, latest or all. references=children (or\ndescendants/all) adds what a dataflow or data structure uses;\nreferences=parentsandsiblings on a category scheme adds the\ncategorisations and dataflows filed under it.", "parameters": [ { "description": "dataflow, datastructure, codelist, conceptscheme, categoryscheme or categorisation", "in": "path", "name": "resource", "required": true, "type": "string" }, { "description": "RIDGITAL or all", "in": "path", "name": "agencyID", "required": true, "type": "string" }, { "description": "An id or all", "in": "path", "name": "resourceID", "required": true, "type": "string" }, { "description": "1.0, latest or all", "in": "path", "name": "version", "required": true, "type": "string" }, { "description": "none, children, descendants, parentsandsiblings or all", "in": "query", "name": "references", "type": "string" } ], "produces": [ "text/xml" ], "responses": { "200": { "description": "SDMX-ML 2.1 structure message", "schema": { "type": "string" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/errorResponse" } } }, "security": [ { "ArmidAPIKey": [] }, { "CookieAuth": [] } ], "summary": "SDMX structure", "tags": [ "SDMX structures" ] } } }, "schemes": [], "securityDefinitions": { "ArmidAPIKey": { "description": "Ridgital API key for ARMID Explorer. Format: \"Bearer rdg_\u003ckey\u003e\". Create keys in the Ridgital dashboard under **Account → API Keys**; a key works while the account's ARMID Explorer access is active.", "in": "header", "name": "Authorization", "type": "apiKey" }, "CSRFToken": { "in": "header", "name": "X-CSRF-Token", "type": "apiKey" }, "CookieAuth": { "in": "cookie", "name": "ridgital_session", "type": "apiKey" }, "RelayAPIKey": { "description": "Ridgital Relay API key. Format: \"Bearer rdg_\u003ckey\u003e\". Create keys in the Ridgital Console under **API Keys** (customer login required).", "in": "header", "name": "Authorization", "type": "apiKey" } }, "swagger": "2.0", "tags": [ { "description": "ARMID's category tree, category search and one category.", "name": "Categories" }, { "description": "The time series in a category, and one series' description and newest value.", "name": "Time series" }, { "description": "A time series' values as JSON, CSV or GeoJSON.", "name": "Observations" }, { "description": "The same data as SDMX 2.1: dataflows, data structure, codelists, concepts and the category scheme, in SDMX-ML.", "name": "SDMX structures" }, { "description": "Observations of a dataflow as SDMX-ML Generic, SDMX-JSON or SDMX-CSV.", "name": "SDMX data" } ] }