NALDC

1. Gaining Access

Anyone may access and use the API. However, a data.gov API key must be incorporated into each API request.

2. Rate Limits

We currently limit the number of API requests to a default rate of 1,000 requests per hour per API Key. Exceeding this limit will cause your API key to be temporarily blocked for one hour. More detailed information on rate limits may be found here. Please contact us if you feel you need a higher request rate setting.

3. API Overview

Our RESTful Web Service gives you access to the publications and related information we hold in the NALDC repository.

4. API Module: Search

Use this module to search the publications and related information we hold in the NALDC repository.

URL syntax

Construct your URL for search requests as follows:

GET https://api.nal.usda.gov/naldc/rest/search/?query={}[&parameters]

Request Parameters

• query
This is the only required parameter for the search module.

Enter your search terms with this parameter. You can use a keyword or combination of keywords:

https://api.nal.usda.gov/naldc/rest/search/?query=corn&api_key=DEMO_KEY

Or a fielded search:

https://api.nal.usda.gov/naldc/rest/search/?query=title:corn&api_key=DEMO_KEY
https://api.nal.usda.gov/naldc/rest/search/?query=author:anderson&api_key=DEMO_KEY
https://api.nal.usda.gov/naldc/rest/search/?query=subject:corn&api_key=DEMO_KEY
https://api.nal.usda.gov/naldc/rest/search/?query=abstract:corn&api_key=DEMO_KEY
https://api.nal.usda.gov/naldc/rest/search/?query=journal:climate&api_key=DEMO_KEY
https://api.nal.usda.gov/naldc/rest/search/?query=publication_year:2010&api_key=DEMO_KEY

• page
Specify the results page you wish to retrieve, where applicable. We have a page length of 20 and page numbers start at 1; default value is 1 (i.e. publications 1-20), if the parameter is unspecified.

For example:

https://api.nal.usda.gov/naldc/rest/search/?query=corn&page=10&api_key=DEMO_KEY

• per_page
Specify the results per page that you wish to retrieve, where applicable. We have a per page limit of 100 and page numbering starts at 1; default value is 20 (i.e. publications 1-20), if the parameter is unspecified.

For example:

https://api.nal.usda.gov/naldc/rest/search/?query=corn&page=1&per_page=100&api_key=DEMO_KEY

• format
The response format can be JSON only. (XML support coming soon.) This can be specified in the API request or sent in the request header: Content-Type.

Example:

https://api.nal.usda.gov/naldc/rest/search/?query=corn&format=json&api_key=DEMO_KEY

5. API Module: Article

Use this module to request an article metadata and related information.

URL syntax

Construct your URL for article requests as follows:

GET https://api.nal.usda.gov/naldc/rest/articles/[id]/?api_key=[api_key]

For example:

https://api.nal.usda.gov/naldc/rest/articles/1758938/?api_key=DEMO_KEY
https://api.nal.usda.gov/naldc/rest/articles/1758938.json/?api_key=DEMO_KEY