API design philosophy

This page describes the design principles behind the API. Understanding these conventions will assist with integration and provide predictability as new features are introduced.

The API serves H2GC's curated datasets without transformation. It does not aggregate or compute derived metrics — data is returned as stored, with optional filtering and pagination. Any aggregation or analysis is performed on the client side.

2. One pattern for all datasets

All datasets are queryable through the same /financials endpoint using the metric parameter. The catalog endpoint provides a list of available datasets. This approach offers several advantages:

There is no need to learn different endpoints for different data types
Integration code functions identically regardless of the metric
New datasets become accessible immediately without client-side code changes

3. Self-describing responses

Every response includes a meta object that describes the request parameters:

{
  "meta": {
    "dataset": "ggr_annual",
    "metric": "ggr_annual",
    "granularity": "annual",
    "filters_applied": { "country": ["United Kingdom"] },
    "row_count": 100
  }
}

This makes responses straightforward to debug and log without reference to the original request.

4. Dimensions and values

Data rows are separated into dimensions (the attributes describing the row) and values (the numeric data). This consistent structure simplifies the construction of tables, charts, and data pipelines.

5. Cursor-based pagination

The API uses opaque cursors rather than page numbers or offsets. This avoids consistency issues when paginating through large result sets.

Data freshness

H2GC datasets are refreshed on a monthly cadence. Between refreshes, query results for the same parameters are identical. This has practical implications:

Cache aggressively — responses can be cached for days or weeks without becoming stale
Batch fetches — there is no benefit to polling the same query repeatedly within a month
Plan sync jobs accordingly — a monthly or fortnightly sync is typically sufficient

Conventions

URL structure

/api/v1/{resource}

All endpoints are under /api/v1
Resource names are lowercase
Query parameters use snake_case

Response envelope

All data responses follow this structure:

{
  "meta": {},
  "data": [],
  "pagination": {}
}

For collection endpoints that do not paginate (e.g. the catalog), the pagination object is omitted.

Error format

All errors return:

{
  "error": "Human-readable message",
  "details": {}
}

The details field is present only on validation errors (400 responses).

Dates and times

Dates use ISO 8601 format: YYYY-MM-DD
Timestamps use ISO 8601 with timezone: 2024-01-15T10:30:00Z
Period ranges use colon-separated dates: 2024-01-01:2024-12-31

Currency

Financial datasets include an fx dimension that indicates the currency of the values (e.g. USD, GBP, EUR). Filtering by fx=USD returns values in US dollars; omitting the filter returns data in all available currencies. The FX reference dataset provides the exchange rates used for currency conversion.

Core principles

1. Read-only data access