openapi: 3.1.1 info: title: "National Archives Find Case Law: Public API" version: 0.5.1 description: |- Our API provides access to judgments and other documents held by The National Archives and published via the Find Case Law service. ## Open Justice Licence The National Archives has worked in collaboration with The Ministry of Justice and the Judicial Executive Board to design a new licensing framework for the reuse of case law as data. The [Open Justice licence](https://caselaw.nationalarchives.gov.uk/open-justice-licence) is designed to protect the personal data within the records while supporting the principles of Open Justice. The Open Justice licence allows you to copy, publish, distribute and transmit case law data. It permits you to use the data commercially, for example, by combining it with other information, or by including it in your own product or application. There are certain conditions that apply under this licence. You do not need to apply to re-use Find Case Law records if your re-use complies with the terms and conditions of the Open Justice Licence. **The Open Justice licence does not permit computational analysis.** If you intend to do any programmatic searching in bulk across the Find Case Law records to identify, extract or enrich contents within the records you will need to [apply to perform computational analysis](https://caselaw.nationalarchives.gov.uk/re-use-find-case-law-records/licence-application-process). There are no application charges. ## Document identifiers Documents in Find Case Law are identified in two different ways, one which is better for machines and one which is better for humans: ### Document URI Every document in Find Case Law has a unique machine-readable identifier which is not designed to be human-facing. You should prefer using this identifier internally when referencing Find Case Law documents, as it is stable and globally unique. Document URIs can contain the characters `a-z`, `0-9`, `/` and `-`. #### Documents prior to April 2025 Documents which were submitted to the National Archives prior to April 2025 will have a URI in the form `court/year/sequence`, for example `uksc/2024/123`. Although this looks like it contains many attributes from a Neutral Citation Number, you should _not_ treat it as such and attempt to extract information from it. #### New-style URIs Documents submitted to the National Archives from April 2025 onwards will usually have a URI which looks something like `d-f11e093f-8a53-4e43-8dd8-1531b5d8f018`. These will always begin with a `d-`. ### Structured identifiers In addition to the Document URI, all documents will also have one or more "structured identifiers" representing ways which humans can refer to a document. This currently includes Find Case Law Identifiers (for all documents) and Neutral Citation Numbers (for judgments which have them), but may be extended in future. Each identifier will have – as a minimum – a `type`, a `value` and a `slug` which can be turned into a human-facing URL by appending it to `https://caselaw.nationalarchives.gov.uk`. Identifiers are _not_ guaranteed to be unique to a single document. #### Examples | Type | `type` | Example `value` | Example `slug` | | ------------------------ | -------- | ----------------- | ----------------| | Find Case Law Identifier | `fclid` | `cw7s3kws` | `tna.cw7s3kws` | | Neutral Citation Number | `ukncn` | `[2024] UKSC 123` | `uksc/2024/123` | #### Preferred identifier Each document will have exactly one preferred identifier, determined by the Find Case Law system, which it will prefer for displaying to users and generating public-facing URLs. You must _not_ make any assumptions about the type of this preferred identifier, as it may change. ## Rate limits You can make up to **1,000 requests** (of any type) to Find Case Law in any **rolling five minute period** per IP address. If you have exceeded this, you will receive a `HTTP 429` error code. If you need to make more requests, please email [caselaw@nationalarchives.gov.uk](mailto:caselaw@nationalarchives.gov.uk) to talk about your requirements. ## Give us your feedback We are still actively developing the Find Case Law service. This includes improving how you can access our data programmatically. If you have suggestions, comments or queries about the API or the data it provides, please email them to [caselaw@nationalarchives.gov.uk](mailto:caselaw@nationalarchives.gov.uk). If you'd be interested in taking part in user research to help improve the service, please [sign up](https://www.smartsurvey.co.uk/s/CaseLaw-research/). termsOfService: "https://caselaw.nationalarchives.gov.uk/terms-of-use" contact: email: caselaw@nationalarchives.gov.uk url: "https://caselaw.nationalarchives.gov.uk/" name: Find Case Law license: name: Open Justice Licence url: "https://caselaw.nationalarchives.gov.uk/open-justice-licence" summary: "The Find Case Law API allows you to access court judgments and tribunal decisions held in the [Find Case Law service](https://caselaw.nationalarchives.gov.uk/), operated by the National Archives." servers: - url: "https://caselaw.nationalarchives.gov.uk" description: Find Case Law components: parameters: documentUri: name: document_uri in: path required: true schema: type: string examples: ncn-based: value: uksc/2024/123 summary: An older Neutral Citation Number-based document URI uuid-based: value: d-f11e093f-8a53-4e43-8dd8-1531b5d8f018 summary: A newer document URI description: The unique identifier for this document within Find Case Law. responses: tooManyRequests: description: Too Many Requests documentFeed: description: | An Atom feed of documents, sorted by one of the dates within those documents. content: application/xml: schema: description: List in Atom examples: list: description: An example of a complete response, with only one `entry`. value: | Latest documents, sorted by date the document was first published by the court (newest first) https://caselaw.nationalarchives.gov.uk/atom.xml 2025-04-30T15:00:00+00:00 The National Archives https://caselaw.nationalarchives.gov.uk/open-justice-licence Jarndyce v. Jarndyce 2025-04-30T00:00:00+00:00 2025-04-30T09:54:24+00:00 Upper Tribunal (Lands Chamber) https://caselaw.nationalarchives.gov.uk/id/d-9b51d493-65ba-471f-8f08-c369ec66e3f8 d1b2a59fbea7e20077af9f91b27e95e865061b270be03ff539ab3b73587882e8 d-9b51d493-65ba-471f-8f08-c369ec66e3f8 [2024] UKSC 123 r8d6ps87 document: description: "The contents of a single document, as [Akoma Ntoso XML](https://www.oasis-open.org/standard/akn-v1-0/)." content: application/akn+xml: schema: description: Akoma Ntoso paths: /atom.xml: get: summary: Get an Atom feed of documents description: | Return a list of documents in Find Case Law, ordered by date. Without any parameters, this will order by the most recently handed down judgments and documents first. The parameters used are identical to those used for the advanced search at https://caselaw.nationalarchives.gov.uk/judgments/search: a link to the feed mirroring those search results is available on each search result. Each differently named parameter filters out documents that do not match it. The feed has multiple pages (see the `link` tag with a `rel` attribute of `next` for the next page). Each `entry` element contains a different document's metadata. Not all documents will contain all tags. Notable tags and elements include: * ``: The date the document was first published by the court (for judgments, the 'handed down' date) * ``: The date the XML of the document was last updated in Find Case Law. This may include not only changes to the text, but also minor changes to markup such as formatting or annotations. * ``: A link to the document's page on Find Case Law (with HTML representation, where one exists) * ``: A link to an XML representation of the document * ``: A link to a PDF representation of the document * ``: The [Document URI](#document-uri) in Find Case Law. * ``: One element per [identifier](#document-identifiers) known to relate to this document. * ``: A hash of the text in the document. See [Content Hash](#content-hash) for more. * ``: The location of any images in the XML (e.g. `image1.png`) can be prefixed with this to download those images. Please do not hotlink: the URL here is not guaranteed to be stable. operationId: atomFeed parameters: - name: query required: false in: query schema: type: string description: | Full text search of a judgment. `"financial records"` will only find judgments with those two words in that order. Multiple space-separated words will only find judgments that have all those words. # todo: from_ and to_date_0, _1, _2, 2 is year - name: court required: false in: query schema: type: array items: type: string explode: true description: | A court code. Currently there are two forms of court code, one used in the URL structure (`ewhc/fam`) and one used in the XML court tag `EWHC-Family`. Either can be searched for. If multiple courts or tribunals are given, results from all those courts may be returned. example: - uksc - ukpc - name: tribunal required: false in: query schema: type: array items: type: string explode: true description: | An alias for the `court` parameter. example: - eat - name: party required: false in: query schema: type: string description: | A full-match for a word in the name of a party to the judgment. - name: judge required: false in: query schema: type: string description: | A full-match for a word in the name of a judge or similar involved in the judgment - name: order required: false in: query schema: type: string enum: - date - "-date" - updated - "-updated" - transformation - "-transformation" default: "-date" description: | Which of the dates within the document to use for ordering. Prepend a `-` to sort by newest first. - `date`: The date the document was first published by the court - `updated`: The last date the document was updated in the Find Case Law system, including any changes to its metadata - `transformation`: The date the body of the document was last modified, including changes to either the body text, XML markup, or both - name: page required: false in: query schema: type: integer default: 1 minimum: 1 description: "Where results are across multiple pages, the page of results to return." - name: per_page required: false in: query schema: type: integer default: 50 description: | How many results to list per page. responses: "200": $ref: "#/components/responses/documentFeed" "429": $ref: "#/components/responses/tooManyRequests" tags: - Document metadata "/{document_uri}/data.xml": get: summary: Get document XML operationId: getDocumentByUri responses: "200": $ref: "#/components/responses/document" "429": $ref: "#/components/responses/tooManyRequests" tags: - Document contents description: | Retrieve the XML of a single document based on its identifier. ## A note on images Where a document contains images, the XML will _not_ provide an absolute URL where the image can be found. Instead, all image locations in the XML are relative to an arbitrary root location. To find the root location for a document's assets you will need to find the document's `assets_base` value. At the moment, this is only available via the [Atom feed](#operation/atomFeed). We *strongly* recommend against storing an `assets_base` for the purposes of hotlinking, as these are not guaranteed to be stable. parameters: - $ref: "#/components/parameters/documentUri" "/{court}/{subdivision}/{year}/atom.xml": get: summary: Get a list of recently published or updated documents description: | Deprecated -- will now redirect to `/atom.xml` with relevant parameters Less specific feeds can be gained by omitting the components e.g. `/`, `/2022/`, `/ewhc/` and `/ewhc/ch/` are all valid prefixes to `atom.xml`. Note that a `{court}` is required if there is a `{subdivision}`. operationId: listJudgments parameters: - name: order required: false in: query schema: type: string enum: - date - "-date" - updated - "-updated" - transformation - "-transformation" default: "-date" description: | Which of the dates within the document to use for ordering. Prepend a `-` to sort by newest first. - `date`: The date the document was first published by the court - `updated`: The last date the document was updated in the Find Case Law system, including changes to its metadata - `transformation`: The date the body of the document was last modified, including changes to either the body text, XML markup, or both - name: page required: false in: query schema: type: integer default: 1 minimum: 1 description: "Where results are across multiple pages, the page of results to return." responses: "301": description: Moved Permanently headers: location: schema: type: string description: "https://caselaw.nationalarchives.gov.uk/atom.xml?court={court}/{subdivision}&year={year}&order=-date&page=1" "429": $ref: "#/components/responses/tooManyRequests" tags: - Document metadata deprecated: true parameters: - name: court required: true in: path example: ewca schema: type: string description: The court code to return results for. - name: subdivision required: true in: path example: pat schema: type: string description: The court subdivision code to return results for. - name: year required: true in: path example: 2022 schema: type: integer description: The year to return results for. tags: - name: Document metadata description: | ## Detecting content changes We recommend setting the `order` parameter of the Atom feed to `-transformation` to detect changes made to judgments, as this will list the most recently changed documents first: `https://caselaw.nationalarchives.gov.uk/atom.xml?order=-transformation` ### Using the date If you always want to have the latest XML of a document, even if the changes are only to markup and the content has not changed (for example, if we have made some formatting improvements) the easiest way is to store the date the document was last changed. You can find this as either: - The `date` attribute of the `` tag within the LegalDocML representation - The `` element of an `` in the Atom feed You can then compare this stored date to the `` element in the Atom feed, and only take action if the Atom feed's date is more recent. ### Using the content hash If you are not interested in minor improvements to the XML document markup, and only care about changes to the document itself, you can use the content hash. This hash is generated by removing all XML markup and leaving only the body text of the document, and then generating a SHA256 hash of that text. As such this hash should be stable across things such as formatting changes, and will only change if the text of the document does. You can find the content hash as either: - The `` element within the `` element of the LegalDocML representation - The `` element of an `` in the Atom feed By storing the content hash when you first retrieve a document you can then compare it in future to detect if the text has changed. - name: Document contents description: | ## Document formats Documents within Find Case Law are mostly available as structured XML, although some older documents are only available as PDFs. ### XML Where documents exist as XML, these have been submitted for publication by the courts as a Microsoft Word document. This has then been automatically converted to XML, marked up according to the [international data standard (LegalDocML)](https://groups.oasis-open.org/communities/tc-community-home2?CommunityKey=3425f20f-b704-4076-9fab-018dc7d3efbe). This data includes: - Neutral Citation - Court / Chamber - Date - Case Name - Party Names - Judges' Names XML documents are then automatically converted to HTML for publication on the Find Case Law website. For documents which have been submitted directly to the National Archives our legal editorial team have checked data for consistency and accuracy. However, older documents have not always been checked in this way and you may discover inconsistencies in the metadata. If you do, you can report data errors to [caselaw@nationalarchives.gov.uk](mailto:caselaw@nationalarchives.gov.uk). ### PDF Some documents, particularly historic documents, may only exist as PDFs. In these cases we will provide as much metadata regarding the document as we are able, although this may not be as complete as in an XML document.