

API Reference
Reading Datasets
Version: 4.0
Updated: 14th July 2024
Updated: 14th July 2024
Overview
Read a public dataset with a GET request. The API treats datasets as JSON documents.
The dataset ID can be found in the URL of the dataset page, or in the metadata export.
GET
https://data.website/api/dataset/:idPath Parameters
:id | 5-character ID of the dataset, eg. "ab12x" | string | Required |
HTTP Headers
Authorization | Optional API key used to view your private datasets. | string | Optional |
HTTP Return Codes
200 | Returns the full dataset JSON. |
403 | API key does not have read permissions to this private dataset. |
404 | The dataset does not exist. |
Example
import requests, json
dataset_id = "20abc"
url = f"https://data.website/api/dataset/{dataset_id}"
response = requests.get(url)
print(json.dumps(response.json(), indent=2))
{
"id": "200k2", // [immutable]
"title": "Freedom of Information Requests",
"description": "<p>Page content <img src=\"...\" /></p>",
// [...full JSON structure...]
}
JSON Reference
This JSON structure is designed to be easy to read and write using JSON Patch.
Refer to the Export API for a simpler full-site export.
example_dataset.json
{
// -- [CONTENT]
// ID the dataset:
"id": "20abc", // [immutable]
// Title is used to generate friendly webpage URL:
// eg. https://data.website/dataset/20abc/freedom-of-information-requests
"title": "Freedom of Information Requests",
// The body of the page:
"description": "<p>Page content <img src=\"...\" /></p>",
// The same as description, with HTML stripped:
"descriptionText": "Page content",
// Optional iframe appended to the end of the page:
"descriptionIframe": "https://.../iframe.html",
// The masthead image at the top of the page:
"masthead": "london-borough-of-barnet",
// Tags are used by the search engine:
"tags": ["FOI Requests", "FOI", "Freedom of Information"],
// Topics are pre-defined in settings.
// They create designated landing pages for similar datasets:
"topics": ["community-information", "council-and-democracy"],
// -- [SIDEBAR CONTENT]
// The next review date:
"nextReviewDate": "2025-01-15",
// The licence:
"licence": {
"url": "https://.../doc/open-government-licence/version/3/",
"title": "UK Open Government Licence (OGL v3)"
},
// Generates a clickable "contact" link in the sidebar:
"contact": {
"email": "[email protected]",
"title": "Barnet Open Data Team"
},
// Custom fields are pre-defined in settings.
// You can store any key-value pairs here as string or string[]
"custom": {
"unit": "Assurance",
"service": "Information Management Team",
"retention": "3 months",
"geography": ["London", "Barnet"]
},
// -- [FILES]
"resources": {
// "resources" stored file uploads with keys as the file ID.
// These 3-character strings are automatically generated.
// (UUID keys are also supported)
"k93": {
// URL to download the file:
"url": "https://data.website/download/[...]", // [immutable]
// File order in the dataset:
"order": 0,
// File title:
"title": "FOI requests received 2020-25",
// Optional description, plain text:
"description": "This file contains [...]",
// Time frame covered by the file, as ISO month strings:
"timeFrame": {
// Both keys are optional:
"gte": "2020-01", // "Greater Than or Equal" is the "From" date
"lte": "2024-11" // "Less Than or Equal" is the "To" date
},
// File format is automatically detected:
"format": "csv", // [immutable]
// Hash of the file is automatically generated:
"hash": "2cdf3a47738b93492906e3ad7e415d1a", // [immutable]
// File size in bytes is automatically generated:
"size": 1337303, // [immutable]
// File origin path is used internally to fetch from storage:
"origin": "/barnet/dataset/..." // [immutable]
}
},
"links": {
// "links" stores external URLs listed under the file downloads section.
// Keys work the same as those for "resources".
// The webpage interleaves the links with the resources.
"0xd": {
// The URL to the link:
"url": "https://...",
// The order of the link in the webpage:
"order": 3,
// The title of the link:
"title": "Transport for London Updates and Information",
// The description of the link:
"description": "",
// The Quality Assurance analysis of the link:
// Note: This is automatically updated every 24 hours.
"qa": { // [immutable]
// Timestamp of the last QA check:
"timestamp": "2025-01-24T19:17:04.371Z",
// Content ETAG:
"hash": null,
// Size of the content:
"size": null,
// MIME type of the content:
"mimetype": "text/html;charset=utf-8",
// HTTP status of the content:
"httpStatus": 200
}
},
},
// -- [ACCESS CONTROL]
// The owner team. All members can edit the dataset:
"team": "vrv65",
// Sharing: "public" or "private".
// Public datasets are visible to all users:
"sharing": "public",
// Collaborators: Additional user IDs who can edit the dataset:
"collaborators": [12, 495, 1024],
// Read users: user IDs who can read the dataset: [private datasets only]
"readusers": [88],
// Read teams: team IDs who can read the dataset: [private datasets only]
"readteams": ["abc12"],
// -- [METADATA]
// Creation timestamp metadata:
"createdAt": "2019-02-05T16:34:18.000Z",
// Last update timestamp metadata:
// Note: This is not automatically updated when submitting a patch.
"updatedAt": "2025-01-21T16:10:03.385Z",
// ID the website
"site": "barnet" // [immutable]
}