Beta This is a new service – your feedback will help us to improve it.

General

• Get started
• Roles
• Requesting restricted data
• Data request questions

Publishers

• Publishing on the Data Marketplace
• Details for your listing

Developers

• API
• Search your datasets
• Submit dataset
• Get dataset
• Update dataset
• Delete dataset

API endpoints

Submit dataset

Creates a dataset resource. The path to the newly created resource will be returned in the Location response header.

POST /datasets

Request body

• title required: string max length: 200

  The full and formal name given to an information resource. A name given to the distribution.

• type required: string

  Values: Data Set, Data Service, Data Group, Data Share

  Topic: A controlled term that expresses the broad topical content of an information resource. Subject: A controlled term that expresses a topic of the intellectual content of an information resource.

• accessRights: string

  Values: RESTRICTED, OPEN, COMMERCIAL, INTERNAL

  A rights statement that concerns how the distribution is accessed.

• contactPoint required: array of objects

  Contact information

  Object parameters:

  name string required

  email string required

  role string
• created: date time string
• creator: string max length: 75

  The organisation responsible for creating the catalogued resource.

• description required: string max length: 4096

  A concise narrative of the content of an catalogued resource.

• identifier: string max length: 50

  A unique number, code, or reference value assigned to a catalogued resource within the catalogue.

• issued: date time string
• license: object

  A legal document under which the resource is made available.

• keyword: array of strings

  Uncontrolled terms (words or phrases) assigned to describe an information resource.

• modified: date time string
• publisher: string max length: 75

  The entity responsible for making the catalogued resource publicly available.

• securityClassification: string

  Values: OFFICIAL, SECRET, TOP_SECRET, NOT_APPLICABLE

  An information security designation that identifies the minimum level of protection assigned to an information resource.

• status: string

  Values: Draft, Published, Withdrawn, Deleted

  Lifecycle status of resource within catalogue

• supplierIdentifier: string max length: 50

  A unique number, code, or reference value assigned to a catalogued resource a third party (supplier's) system.

• theme: array of strings

  Topic: A controlled term that expresses the broad topical content of an information resource. Subject: A controlled term that expresses a topic of the intellectual content of an information resource.

• distribution: array of objects

  A collection of distributions

  Object parameters:

  accessService array of strings

  A reference to the service that provided the data

  accessURL string

  The location from which the Dataset can be accessed. To be used instead of downloadURL when describing an API

  description string

  Human readable description of the distribution

  downloadURL string

  The location from which the Dataset can be downloaded or Web Page accessed (when mediaType text/html)

  format string

  Human readable description of the format of the data provided by the distribution

  mediaType array of strings

  The IANA media type, or file format, type, or extention, of the distribution file.

  title string

  A title for the distribution

• updateFrequency: string

  The schedule for how often the data is updated

Example

Creates a resource that describes a dataset with a CSV file distribution.

                {
  "supplierIdentifier": "acme-123",
  "modified": "Microsoft.OpenApi.Any.OpenApiDateTime",
  "status": "Published",
  "title": "Advance Passenger Information",
  "description": "Travel data and personal data given to airlines by passenger. API covers  both inbound and outbound air passengers. API includes the passenger’s full name, nationality, date of birth, gender and travel document number, type and country of issue.The data does not include those arriving by sea or rail routes, by private aircraft or via the Common Travel Area (CTA).",
  "type": "Data Set",
  "theme": [
    "Transport and infrastructure",
    "Population and society"
  ],
  "keyword": [
    "Air travel",
    "Passport",
    "Airports",
    "leaving UK",
    "entering UK"
  ],
  "contactPoint": [
    {
      "name": "Rob Nichols",
      "email": "robert.nichols@digital.cabinet-office.gov.uk",
      "role": "contact"
    }
  ],
  "license": {
    "title": "Creative Commons",
    "licenseURL": "https://creativecommons.org/licenses/by/4.0"
  },
  "publisher": "academy-for-social-justice",
  "securityClassification": "OFFICIAL",
  "accessRights": "OPEN",
  "distribution": [
    {
      "title": "CSV download",
      "description": "Complete dataset provided as a downloadable file",
      "accessService": [
        "8d085327-21b6-4d8b-9705-88faad231d23"
      ],
      "downloadURL": "http://example.com/path/to/file.csv",
      "format": "CSV file",
      "mediaType": [
        "text/csv"
      ]
    },
    {
      "title": "Rest API",
      "accessURL": "http://example.com/api/",
      "description": "A fully queryable REST API with JSON and XML output",
      "format": "API"
    },
    {
      "title": "Web Page",
      "description": "A web page that provides the data, links to downloads, or documentation.",
      "downloadURL": "http://example.com/path/to/page",
      "format": "Web page",
      "mediaType": [
        "text/html"
      ]
    }
  ]
};
                                                                                                

Responses

201

Created

400

Bad Request

application/json

object

• code: string

  A system specific code for the global error raised

• errors: array of objects

  An array of the specific error details

• message: string

  Summary description of the nature of the error

Examples

Validation problems with Dataset metadata.

                    {
  "message": "Validation failures",
  "code": "DM00012",
  "errors": [
    {
      "type": "Fatal",
      "detail": "The attribute 'summary' is too long. It should be less than 250 characters",
      "location": "/summary"
    },
    {
      "type": "Fatal",
      "detail": "The distribution byteSize of '1Mb' is not an integer",
      "location": "/distribution/byteSize"
    }
  ]
};

API client does not have permissions to publish as the specified publisher.

                    {
  "message": "Validation failures",
  "code": "DM00012",
  "errors": [
    {
      "type": "Fatal",
      "detail": "You cannot create datasets for the specified 'publisher'",
      "location": "/publisher"
    }
  ]
};

409

Conflict

application/json

object

• code: string

  A system specific code for the global error raised

• errors: array of objects

  An array of the specific error details

• message: string

  Summary description of the nature of the error

Example

Internal service conflict.

                    {
  "message": "The datset cannot be created because a dataset with identifier  already exists. To update an existing dataset please call operation PATCH /datasets/{dataset-id} operation instead.",
  "code": "DM00014",
  "errors": []
};