Ridgital ARMID Explorer API

The 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 API, with any SDMX client. It is the same data the Data tab of ARMID Explorer shows.

Getting Started

• Request ARMID Explorer access. The data API needs the Data section in your access, which runs until a set date.
• 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).
• Send the key with every request.

An 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.

Authentication

Authorization: Bearer rdg_<your_api_key>

Base URL

https://ridgital.com/api/v1/armid/data

Quick start

# 1. The category tree
curl -H "Authorization: Bearer $KEY" https://ridgital.com/api/v1/armid/data/categories

# 2. Find a category
curl -H "Authorization: Bearer $KEY" "https://ridgital.com/api/v1/armid/data/categories/search?q=inflation"

# 3. The time series in it
curl -H "Authorization: Bearer $KEY" "https://ridgital.com/api/v1/armid/data/categories/{id}/series?pageSize=50"

# 4. A series' observations, as CSV ({id} is the series key from step 3, e.g. M.AM.IHB2Q7K3MZ4XA)
curl -H "Authorization: Bearer $KEY" "https://ridgital.com/api/v1/armid/data/series/{id}/observations?limit=all&format=csv" -o series.csv

Conventions

• 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.
• 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.
• Lists are paged: page (from 1) and pageSize (up to 100). A page is {"items": [...], "page", "pageSize", "totalItems", "totalPages"}.
• 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.
• 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).
• 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.
• 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.
• Formats: format=json (default), format=csv (one column per dimension and metric) or format=geojson (a FeatureCollection of the observations that have a location).
• Errors are {"error": "message", "code": "machine_readable_code"}.

SDMX

Every 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.

Structures 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).

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.

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.

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.

import io, pandas as pd, requests

r = requests.get(
    "https://ridgital.com/api/v1/armid/sdmx/data/DF_FOOD_MARKET_PRICES/M.AM...",
    params={"format": "csvdata", "startPeriod": "2024-01"},
    headers={"Authorization": "Bearer rdg_<your_api_key>"},
)
df = pd.read_csv(io.StringIO(r.text))  # one row per observation

Categories

ARMID's category tree, category search and one category.

Time series

The time series in a category, and one series' description and newest value.

Observations

A time series' values as JSON, CSV or GeoJSON.

SDMX structures

The same data as SDMX 2.1: dataflows, data structure, codelists, concepts and the category scheme, in SDMX-ML.

SDMX data

Observations of a dataflow as SDMX-ML Generic, SDMX-JSON or SDMX-CSV.