DataPress logo
API Reference

Reading Datasets

Version:  4.0
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/:id
Path Parameters
:id5-character ID of the dataset, eg. "ab12x"stringRequired
HTTP Headers
AuthorizationOptional API key used to view your private datasets.stringOptional
HTTP Return Codes
200Returns the full dataset JSON.
403API key does not have read permissions to this private dataset.
404The 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))

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]
}