Discovery System RESTful API

The National Archives API

Our API allows developers to query the search engine and our Catalogue database within the Discovery service application programmatically, and returns results in XML for further processing. The service is offered as a beta with some functionality still to be developed. In the meantime we welcome feedback on the initial functionality in this release.

If you make a request to this service you are deemed to have accepted the terms and conditions

Understanding the Discovery service catalogue

A little understanding of the internals of the Discovery service catalogue will help with the API methods below. The catalogue is a seven-level hierarchical database of our records (read a more detailed description). When using the API methods below, you’ll find that some of the normally ‘invisible’ levels (levels which are present but not reflected in the citable reference, such as ‘Division’) will become relevant and may be initially confusing when using methods like Children which traverse the levels of the catalogue.

Every record in our catalogue is an Information Asset and is uniquely referenced by its IAID. Some of the Information Assets have children, and this parent-child relationship defines the catalogue hierarchy.

Every Information Asset is also categorised by subject, date range and department (“Department” in this context being the top level of the catalogue previously called a “Lettercode”). These categories can be used to further filter the results, and multiple values for each filter can be semi-colon delimited. The acceptable values for these categorisations are as follows:

Detailed view of search filters

Expand selection Show subject search filters

Subject

  • C10001 Aid and development
  • C10002 Air Force
  • C10003 Air transport
  • C10004 Archives and libraries
  • C10005 Art, architecture and design
  • C10006 Badges and insignia
  • C10007 Banking
  • C10008 Canals and river transport
  • C10009 Census
  • C10010 Charities
  • C10011 Chartism
  • C10012 Children
  • C10013 Clothing
  • C10014 Coal
  • C10015 Common land
  • C10016 Communications
  • C10017 Communism
  • C10018 Computing
  • C10019 Conflict
  • C10020 Conscientious objection
  • C10021 Construction industries
  • C10022 Conveyancing
  • C10023 Crime
  • C10024 Crown lands and estates
  • C10025 Debt
  • C10026 Democracy
  • C10027 Devolution
  • C10028 Diaries
  • C10029 Disability
  • C10030 Disarmament
  • C10031 Disasters and emergencies
  • C10032 Disease
  • C10033 Education
  • C10034 Electoral reform
  • C10035 Events and exhibitions
  • C10036 Farming
  • C10037 Fascism
  • C10038 Fishing
  • C10039 Food and drink
  • C10040 Forestry
  • C10041 Freemasons
  • C10042 Friendly societies
  • C10043 Government finances
  • C10044 Hospitals
  • C10045 Housing
  • C10046 Hunting
  • C10047 Inflation
  • C10048 Intelligence
  • C10049 International
  • C10050 Internment
  • C10051 Iron, steel and metals
  • C10052 Labour
  • C10053 Landed estates
  • C10054 Literature
  • C10055 Litigation
  • C10056 Manors
  • C10057 Manufacturing
  • C10058 Maps and plans
  • C10059 Marriage and divorce
  • C10060 Medals
  • C10061 Medicine
  • C10062 Mental illness
  • C10063 Merchant seaman
  • C10064 Migration
  • C10065 Military personnel
  • C10066 Mining and quarrying
  • C10067 Museums and galleries
  • C10068 Mutual societies
  • C10069 National debt
  • C10070 National Health Service
  • C10071 Nationality
  • C10072 Navy
  • C10073 Nuclear energy
  • C10074 Oil and gas
  • C10075 Operations, battles and campaigns
  • C10076 Pardons
  • C10077 Pay and pensions
  • C10078 Performing arts
  • C10079 Photography and film
  • C10080 Piracy and privateering
  • C10081 Planning
  • C10082 Policing
  • C10083 Population
  • C10084 Poverty
  • C10085 Prisons
  • C10086 Public disorder
  • C10087 Race relations
  • C10088 Radio and television
  • C10089 Railways
  • C10090 Rationing
  • C10091 Refugees
  • C10092 Regiments and Corps
  • C10093 Religions
  • C10094 Religious discrimination and persecution
  • C10095 Renewable energies
  • C10096 Research
  • C10097 Resources
  • C10098 Road transport
  • C10099 Royal Parks
  • C10100 Royalty
  • C10101 Sewerage
  • C10102 Sex and gender
  • C10103 Shipping
  • C10104 Slavery
  • C10105 Sports
  • C10106 Taxation
  • C10107 Tithes
  • C10108 Trade and commerce
  • C10109 Transportation
  • C10110 Travel and tourism
  • C10111 Treason and rebellion
  • C10112 Treaties and alliances
  • C10113 Votes for women
  • C10114 Weapons
  • C10115 Welfare
  • C10116 Wills and probate
  • C10117 Witchcraft
  • C10118 Personal and family papers

Expand selection Show date range search filters

Date range

  1. 1000-1099
  2. 1100-1199
  3. 1200-1299
  4. 1300-1399
  5. 1400-1499
  6. 1500-1599
  7. 1600-1699
  8. 1700-1799
  9. 1800-1899
  10. 1900-1924
  11. 1925-1949
  12. 1950+

Expand selection Show department search filters

Department

  • A
  • AB
  • ACT
  • ADM
  • AE
  • AF
  • AH
  • AIR
  • AJ
  • AK
  • AM
  • AN
  • AO
  • AP
  • AR
  • ASSI
  • AST
  • AT
  • AVIA
  • AW
  • AX
  • AY
  • B
  • BA
  • BC
  • BD
  • BE
  • BF
  • BH
  • BJ
  • BK
  • BL
  • BM
  • BN
  • BP
  • BR
  • BS
  • BT
  • BV
  • BW
  • BX
  • BY
  • C
  • CAB
  • CAOG
  • CB
  • CD
  • CE
  • CF
  • CHAR
  • CHES
  • CJ
  • CK
  • CL
  • CM
  • CN
  • CO
  • COAL
  • COPY
  • COU
  • CP
  • CRES
  • CRIM
  • CSC
  • CSPR
  • CT
  • CUST
  • CV
  • CW
  • CX
  • CY
  • D
  • DB
  • DC
  • DD
  • DEFE
  • DEL
  • DF
  • DG
  • DH
  • DJ
  • DK
  • DL
  • DM
  • DN
  • DO
  • DPP
  • DR
  • DSIR
  • DT
  • DURH
  • DV
  • DW
  • DX
  • DY
  • E
  • EA
  • EB
  • ECCL
  • ECG
  • ED
  • EF
  • EG
  • EH
  • EJ
  • EL
  • EM
  • EN
  • EP
  • ER
  • ES
  • ET
  • EV
  • EW
  • EXT
  • EY
  • F
  • FA
  • FB
  • FCO
  • FD
  • FEC
  • FG
  • FH
  • FJ
  • FK
  • FL
  • FM
  • FN
  • FO
  • FP
  • FR
  • FS
  • FT
  • FV
  • FW
  • FY
  • GFM
  • GIRO
  • HA
  • HB
  • HCA
  • HD
  • HE
  • HF
  • HK
  • HLG
  • HMC
  • HN
  • HO
  • HP
  • HR
  • HS
  • HT
  • HV
  • HW
  • HX
  • HY
  • IND
  • INF
  • IR
  • J
  • JA
  • JB
  • JC
  • JD
  • JE
  • JF
  • JH
  • JK
  • JL
  • JM
  • JN
  • JP
  • JR
  • JS
  • JT
  • JUST
  • JV
  • JW
  • JX
  • JY
  • KA
  • KB
  • KC
  • KD
  • KE
  • KF
  • KH
  • KJ
  • KL
  • KM
  • KN
  • KP
  • LAB
  • LAR
  • LC
  • LCO
  • LO
  • LR
  • LRRO
  • LS
  • LT
  • MAF
  • MEPO
  • MH
  • MINT
  • MONW
  • MPS
  • MT
  • MUN
  • NATS
  • NDO
  • NG
  • NIA
  • NICO
  • NMM
  • NSC
  • OBS
  • OD
  • OS
  • PALA
  • PC
  • PCAP
  • PCOM
  • PEV
  • PIN
  • PL
  • PMG
  • POST
  • POWE
  • PP
  • PREM
  • PRIS
  • PRO
  • PROB
  • PSO
  • PT
  • PWLB
  • QAB
  • RAIL
  • RECO
  • REQ
  • RG
  • RGO
  • SC
  • SO
  • SP
  • STAC
  • STAT
  • SUPP
  • T
  • TG
  • TITH
  • TS
  • UGC
  • WALE
  • WARD
  • WO
  • WORK
  • ZBOX
  • ZHC
  • ZHL
  • ZJ
  • ZLIB
  • ZMAP
  • ZOS
  • ZPER
  • ZSPC
  • MPO
  • MPZ
  • MPFF
  • MPI
  • MPII
  • MR
  • KY
  • NR
  • KX
  • KT
  • KV
  • MF
  • MFC
  • MFQ
  • MPA
  • MPAA
  • MPB
  • MPBB
  • MPC
  • MPCC
  • MPD
  • MPDD
  • MPE
  • MPEE
  • MPF
  • MPG
  • MPGG
  • MPH
  • MPHH
  • MPK
  • MPKK
  • MPL
  • MPLL
  • MPN
  • MPNN
  • MPQ
  • MPQQ
  • MPT
  • MRC
  • MRQ
  • KW
  • NL
  • KR
  • LK
  • KS
  • LB
  • LD
  • LE
  • LF
  • LH
  • LJ
  • LM
  • LN
  • LP
  • LV
  • LX
  • LY
  • MPM
  • MPP
  • MPR
  • NB
  • NC
  • NE
  • NF
  • NH
  • NJ
  • NK
  • NP
  • NV
  • NW
  • NX
  • NY
  • PB
  • TCB
  • TCC
  • TCD
  • TCK
  • PD
  • PF
  • PH
  • PJ
  • PN
  • PV
  • PX
  • PY
  • RB
  • RC
  • RD
  • RF
  • RH
  • ZWEB
  • RK
  • RL
  • RJ
  • RM
  • RP
  • RS
  • QLIB
  • QLX
  • QPR
  • VC
  • VL
  • RV
  • CA
  • MM
  • RW
  • NT
  • RT
  • QAPS
  • SA
  • SB
  • SD

One method, Search, is processed by our Discovery service search engine. The remainder of the methods take an IAID and return results directly from our Discovery service database.

Using the Search engine

The Search method offers a Basic search and an Advanced search, the Advanced search offering more complex searches with logical operators. The Basic search offers an optional SmartSearch function which will spellcheck the query terms. Please see the detailed documentation for more details on the parameters available for this function.

Operations at http://discovery.nationalarchives.gov.uk/API/

This page describes the service operations at this endpoint.

Uri Method Description
InformationAsset/{id} GET

Service at http://discovery.nationalarchives.gov.uk/

API/InformationAsset/{ID}

Children/{id}/{page} GET

Service at http://discovery.nationalarchives.gov.uk/

API/Children/{ID}/{PAGE}

TotalChildren/{id} GET Service at http://discovery.nationalarchives.gov.uk/ API/TotalChildren/{ID}
Parent/{id} GET

Service at http://discovery.nationalarchives.gov.uk/

API/Parent/{ID}

Siblings/{id}/{PAGE} GET Service at http://discovery.nationalarchives.gov.uk/ API/Siblings/{ID}/{PAGE}
Search/{SMARTSEARCH}/{ADVANCEDSEARCH}/{PAGE}?{query} GET

Service at http://discovery.nationalarchives.gov.uk/API/Search/

{SMARTSEARCH}/{ADVANCEDSEARCH}/{PAGE}?query={QUERY}&allWords={ALLWORDS}&exactPhrase={EXACTPHRASE}&orWords1={ORWORDS1}&orWords2={ORWORDS2}&orWords3={ORWORDS3}&notWords1={NOTWORDS1}&notWords2={NOTWORDS2}&notWords3={NOTWORDS3}&subjects={SUBJECTS}&timePeriods={TIMEPERIODS}&departments={DEPARTMENTS}&startDate={STARTDATE}&endDate={ENDDATE}&citableReference={CITABLEREFERENCE}&numberOfResultsPerPage={NUMBEROFRESULTSPERPAGE}

Search/{SMARTSEARCH}/{ADVANCEDSEARCH}/{PAGE}?{query} GET Service at http://discovery.nationalarchives.gov.uk/API/Search/ {SMARTSEARCH}/{ADVANCEDSEARCH}?query={QUERY}&allWords={ALLWORDS}&exactPhrase={EXACTPHRASE}&orWords1={ORWORDS1}&orWords2={ORWORDS2}&orWords3={ORWORDS3}&notWords1={NOTWORDS1}&notWords2={NOTWORDS2}&notWords3={NOTWORDS3}&subjects={SUBJECTS}&timePeriods={TIMEPERIODS}&departments={DEPARTMENTS}&startDate={STARTDATE}&endDate={ENDDATE}&citableReference={CITABLEREFERENCE}&numberOfResultsPerPage={NUMBEROFRESULTSPERPAGE}

Examples

You will need API access to view these example links. Please follow the instructions on Labs.

Examples

Return the first page of search results for records matching “witchcraft”:

http://discovery.nationalarchives.gov.uk/API/Search/false/false/1?query=witchcraft

The returned data includes the subjects into which records have been categorised in its Subjects element, for example the first record returned at the time of writing is categorised in C10117 Witchcraft, C10023 Crime and C10049 International. By performing an Advanced search we can limit the results to particular subjects. For example, the following query will find records featuring the word witchcraft and categorised with subject C10059 (Marriage and Divorce):

http://discovery.nationalarchives.gov.uk/API/Search/false/true/1?allWords=witchcraft&subjects=C10059

Querying the Catalogue directly

PCOM 3 Example

Some series in our catalogue contain structured data, for example PCOM 3 (Licences for early release from prison) has a standardised ScopeContent description across the entire series so could be extracted and parsed into a dataset. Here’s how you might extract this data:

First we need to identify the IAID of the container series, PCOM 3. The Search method allows searching for Document References, so the following query will return records matching “PCOM 3”: http://discovery.nationalarchives.gov.uk/API/Search/false/false?query=PCOM%203

Checking the CitableReference values we see that the first search result is for an Information Asset which represents the series PCOM 3. We see that the IAID for this series is 11498.

We can find out how many Child IAs PCOM 3 has by supplying its IAID to the TotalChildren method: http://discovery.nationalarchives.gov.uk/API/TotalChildren/C11498

Apparently 770 IAs have PCOM 3 as their parent. To find out more about those children we can call: http://discovery.nationalarchives.gov.uk/API/Children/C11498/1

This returns the first page of Child IAs for PCOM 3. The IAID of the first child IA is 2389021, and its Citable Reference is “PCOM 3/1”. The SourceLevelId value shows that this IA is at level 6 of the catalogue (i.e. a Piece). The descriptions may be more granular still if the Piece has been Itemised. Let’s check if PCOM 3/1 has further description by checking if it has any children: http://discovery.nationalarchives.gov.uk/API/TotalChildren/C2389021

This reveals that PCOM 3/1 has been itemised and has 100 child Information Assets. We need to get the IAIDs of those children and then iterate through them, sending them to the InformationAsset method to return the detailed descriptions. http://discovery.nationalarchives.gov.uk/API/Children/C2389021/1

This returns InformationAssetIdentity objects which are a brief summary of the IA, but include the IAID which can be sent to the InformationAsset method to return the detailed IA information. The first child of PCOM 3/1 is PCOM 3/1/1 with IAID 10127419 http://discovery.nationalarchives.gov.uk/API/InformationAsset/C10127419

C 3 Example

C 3 is another series where the information has been entered in a standardised format which could be parsed into a structured dataset.

Get the IAID for C 3:

http://discovery.nationalarchives.gov.uk/API/Search/false/false/1?query=C%203

Get a list of its Children:

http://discovery.nationalarchives.gov.uk/API/Children/C3566/1

The children of C 3 are at level 6, piece level (though confusingly, the citable reference of these pieces are of the form c3/x/x, which would more commonly be an item reference). For each child we need to:

  1. confirm if it has children
  2. fetch the DetailedInformationAsset object
  3. if there are Children, call this procedure recursively for them

The method calls we need to make for each child IA are therefore:

http://discovery.nationalarchives.gov.uk/API/TotalChildren/[IAID]

http://discovery.nationalarchives.gov.uk/API/InformationAsset/[IAID]

If TotalChildren > 0, recurse

Send us feedback