How to use

This tool converts between the legacy ONS API format and the new beta API format. You can:

• Enter a 4-letter CDID code, for example:
  • d7g7 - CPI Annual Rate
  • l55o - GDP Quarter on Quarter Growth
  • mgsx - Unemployment Rate
  • lf24 - Employment Rate
  • ihyq - GDP Chained Volume Measure
• Or paste a legacy URL (e.g., https://api.ons.gov.uk/timeseries/d7g7/dataset/mm23/data)

API Endpoint

Example API calls:

• Using CDID: ?code=d7g7&format=json
• Using URL: ?url=...&format=json
• Data only (CDID): ?code=d7g7&format=json&data_only=true
• Data only (URL): ?url=...&format=json&data_only=true

Documentation

The tool can be used programmatically with the following endpoints:

• Web Interface: ?code=d7g7 or ?url=https://api.ons.gov.uk/timeseries/d7g7/dataset/mm23/data
  Returns the HTML interface with results


• Full JSON Response: ?code=d7g7&format=json
  Returns complete response including metadata:

  {
      "success": true,
      "legacy_url": "...",
      "new_url": "...",
      "title": "...",
      "data": { ... }
  }



• Data-Only Response: ?code=d7g7&format=json&data_only=true
  or ?url=https://api.ons.gov.uk/timeseries/d7g7/dataset/mm23/data&format=json&data_only=true
  Returns only the data object from the ONS API

Parameters:

• code: CDID code (e.g., d7g7)
• url: Legacy ONS API URL (alternative to code)
• format: Set to 'json' for API response
• data_only: Set to 'true' to return only the data object (works with both code and url)

Vega Example

Here's an example of how to create a Vega chart using the ONS API data with our CORS proxy:

{
  "$schema": "https://vega.github.io/schema/vega-lite/v5.json",
  "data": {
    "url": "https://eco-cors-proxy.netlify.app/proxy?url=" + 
          "https://economicsobservatory.github.io/api/ons.html" + 
          "?code=l55o&format=json&data_only=true",
    "format": {
      "type": "json", 
      "property": "months"
    }
  },
  "mark": "line",
  "encoding": {
    "x": {"field": "date", "type": "temporal"},
    "y": {"field": "value", "type": "quantitative"}
  }
}

Live Example (GDP Quarter on Quarter Growth):

Limitations

• This page is hosted on GitHub Pages, so the API endpoint does not return the correct JSON headers.
• However, if you have access to JavaScript you can still parse the JSON data from the HTML response.
• This page is hosted on GitHub Pages, so it also does not support native CORS.
• You can use our CORS Proxy to bypass both of these limitations.