API for the National Archives Catalog
About the Catalog API
The National Archives and Records Administration (NARA) offers some of its public data for all of the records in the Catalog in machine readable format via the Catalog Application Programming Interface (API). The open-source Catalog API supports public access to NARA records, facilitates research, and spurs innovation. Application developers can incorporate archival data and metadata into their applications, websites, or datasets.
The API provides access to all available archival descriptions, authority records, metadata about digital objects (i.e. images, videos, etc.), extracted text (such as optical character recognition or OCR text), and public contributions (tags, transcriptions, and comments). The API allows researchers and developers to retrieve metadata in JavaScript Object Notation (JSON) format for any given record or search results set. This method offers added flexibility for advanced search and refinement because the API can search and retrieve using keywords for any field in the system, search within ranges, apply sorts, specify only particular fields to return, or any combination of these options. Bulk export of search results can then be generated leveraging tools such as Python scripts. The API is also writable, which means it can be used to post and manipulate tags, transcriptions, or comments.
To take full advantage of the Catalog API, developers should familiarize themselves by reading about the API for the National Archives Catalog, the Catalog API documentation, and NARA’s Catalog API on GitHub available online. This documentation provides the detailed definitions and descriptions needed to understand the data elements referenced in the Catalog API documentation.
Terms of Use
This service is offered subject to your acceptance of the terms of use and conditions contained herein as well as any relevant sections of the Archives.gov Website Use Policies and Privacy Policy (collectively, "this Agreement").
All users agree they will not use the National Archives Catalog content or Catalog API service for any illegal or defamatory purpose of any nature. The API service will not be used to juxtapose our content with any illegal or defamatory material of any nature. Users will not write via the API in violation of the Citizen Contribution Policy. No attempts to attack the API or the Catalog, gain unauthorized access, or manipulate data will be allowed.
Users will not scrape data or attempt to download all data from the Catalog via the API, which may affect Catalog performance. To download all publicly available Catalog data, please access the National Archives Catalog dataset on the Amazon Web Services Registry of Open Data.
Scope
All of the content, documentation, code and related materials made available to you through the API is subject to these terms. Access to or use of the API or its content constitutes acceptance to this Agreement.
Gaining Access
Anyone may request an API key to access and use the API. An assigned API key must be incorporated into each API request. The default API key is a read-only key. See “Use: To Request A Read/Write API Key" below for details on requesting that your API key can read and write.
Do not share your API key or accidentally publish it along with your code to a public repository like GitHub. If it is brought to NARA’s attention that an API key has been posted publicly or is being misused in violation of the Citizen Contribution Policy, NARA’s Website Use Policies, these API terms or in violation of federal law, the key will be deactivated. To report an accidentally published API key, email Catalog_API@nara.gov to have your API key deactivated and have a new key established.
NARA will monitor quarterly and deactivate any API keys that have not been used during the past 12 months.
If you attempt to use your API key and cannot access the API because your dormant key was deactivated or for any other reason, email Catalog_API@nara.gov and ask for the status of your key to be checked.
Rate Limits
To ensure consistent system and API availability and performance, NARA limits the number of Catalog API requests to a default rate of 10,000 queries per month per API key.
Exceeding this limit will cause the API key to be temporarily blocked until the first of the following month; your API key query rate limit will automatically reset and be renewed on the first of every month.
Most use cases and research needs can be met by the default API limit. If your research or development efforts require a higher limit, please contact Catalog_API@nara.gov with your use case/research need and justification. NARA staff determines the issuance of a higher limit based on the query rate limit types defined below and Catalog API performance.
| Type of Query Rate Limit | Query Rate Limit / Month |
|---|---|
| Default | 10,000 |
| Higher | 150,000 |
| NARA Staff and Contractor | 500,000 |
| NARA Partner (with a signed partnership agreement) | 1,500,000 |
| NARA Catalog Staff and Contractors (NARA Office of Innovation and Information Services Staff and Contractors who work on and test the Catalog) | Zero query limit / unlimited |
Use: Read-Only
An API key is typically used to develop a service(s) to search, display, analyze, retrieve, view and 'get' information from Catalog data.
Use: Write User Contributions
Writing to contributions (examples: tags, comments, and transcriptions) can be enabled for registered Catalog users upon request. All contributions must be in accordance with the Citizen Contribution Policy. Repeated violations of the Citizen Contribution Policy will be grounds for disabling an API key.
Data submitted through the Catalog API is subject to the Federal Records Act and may be archived.
Use: To Request A Read/Write API Key
To request a read/write API key and that your Catalog user account be linked to your API key, email Catalog_API@nara.gov and include your email address and Catalog user name. If you already have a write API key to be converted to a read/write key, include your API key. The following links provide you with additional information:
- Register and Get Started: Contribute to the Catalog
- Login.gov Rules of Use
- Citizen Contribution Policy
Attribution
All services which utilize or access the API should display the following notice prominently within the application:
"This product uses the National Archives Catalog API but is not endorsed or certified by the National Archives and Records Administration."
NARA’s name may be used in order to identify the source of API content subject to these rules. NARA’s logos may not be used on your website without NARA’s specific written permission. NARA’s name, logos, or the like may not be used to imply endorsement of any product, service, or entity, not-for-profit, commercial or otherwise. All use of NARA logos and seals must be in accordance with NARA regulations at 36 CFR 1200.
Modification or False Representation of Content
All content accessed through the API may not be modified or falsely represented and still claim the source is NARA.
Right to Limit
Use of the API may be subject to certain limitations on access, calls, or use as set forth within this Agreement or otherwise provided by NARA. If the National Archives reasonably believes the user has attempted to exceed or circumvent these limits, ability to use the API may be permanently or temporarily blocked. NARA may monitor all use of the API to improve the service or to ensure compliance with this Agreement.
Service Termination
Termination of this Agreement, may be done by refraining from further use of the Catalog API. NARA reserves the right to (1) refuse to provide the API , if it is the NARA's opinion that use violates any NARA policy, or (2) terminate or deny access to and use of all or part of the API at any time for any other reason in its sole discretion. All provisions of this Agreement which by their nature should survive termination including, without limitation, warranty disclaimers, indemnity, and limitations of liability.
Changes
NARA reserves the right, at its sole discretion, to modify or replace this Agreement, in whole or in part, at any time. NARA recommends all users check the terms of use for updates regularly. Continued use of or access to the API following posting of any changes to this Agreement constitutes acceptance of those modified terms. NARA may, in the future, offer new services and/or features through the API. Such new features and/or services shall be subject to the terms and conditions of this Agreement.
The Catalog is still under development and the content is always growing. Please do not cache or store any content returned by the API.
Limited Technical Support
The user understands and agrees NARA will provide limited technical support services in connection with any use of the API. Contact the team at Catalog_API@nara.gov with reports of any technical issues or questions, or to request limited troubleshooting support.
Disclaimer of Warranties
The Catalog API is provided "as is" and on an "as-available" basis. NARA hereby disclaims all warranties of any kind, express or implied, including without limitation, the warranties of merchantability, fitness for a particular purpose, and non-infringement. NARA does not guarantee availability of the API service. NARA makes no warranty that the API will be error free or that access thereto will be continuous or uninterrupted.
Limitations on Liability
In no event will NARA be liable with respect to any subject matter of this Agreement under any contract, negligence, strict liability or other legal or equitable theory for: (1) any special, incidental, or consequential damages; (2) the cost of procurement of substitute products or services; or (3) for interruption of use or loss or corruption of data.
General Representations
All users hereby warrant that (1) use of the API will be in strict accordance with this Agreement, and all applicable laws and regulations, and (2) use of the API will not infringe or misappropriate the intellectual property rights of any third party.
Indemnification
Agreement to indemnify and hold harmless NARA, its contractors, employees, agents, and the like from and against any and all claims and expenses including attorney's fees, arising out of your use of the API, including but not limited to violation of this Agreement.
Miscellaneous
This Agreement constitutes the entire Agreement between NARA and you concerning the subject matter hereof, and may only be modified by the posting of a revised version on this page by NARA.
Disputes
Any disputes arising out of this Agreement and access to or use of the API shall be governed by federal law.
No Waiver of Rights
NARA’s failure to exercise or enforce any right or provision of this Agreement shall not constitute waiver of such right or provision.