U.S. flag

An official website of the United States government

Dot gov

Official websites use .gov
A .gov website belongs to an official government organization in the United States.

Https

Secure .gov websites use HTTPS
A lock ( ) or https:// means you’ve safely connected to the .gov website. Share sensitive information only on official, secure websites.

NALDC

Main content area


1. API Overview

Our RESTful Web Service gives you access to the publications and related information we hold in the NALDC repository. The API provides one module: the Search module, which returns articles that match desired search criteria.


2. Gaining Access

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


3. 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.


4. Using the API

DEMO_KEY can be used (i.e., api_key=DEMO_KEY) if you have not signed up for your own api.data.gov API Key yet. This API key can be used for initially exploring APIs prior to signing up, but it has much lower rate limits, so you're encouraged to signup for your own API key if you plan to use the API (signup is quick and easy). Signup at https://api.data.gov/signup.

The rate limits for the DEMO_KEY are:

  1. Hourly Limit: 30 requests per IP address per hour
  2. Daily Limit: 50 requests per IP address per day

Additionally, "curl" can be used for each request. An example is shown in the query example.


a. API Module: Search

Use this module to search the publications and related information we hold in the NALDC repository. The links that are underlined are live links.

URL syntax

Construct your URL for search requests as follows:

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

For example:

https://api.nal.usda.gov/naldc/rest/search?query=apple&page=2&per_page=10&format=xml&api_key=DEMO_KEY

Request Parameters

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

    Example API Query URL: https://api.nal.usda.gov/naldc/rest/search?query=id:7112643&api_key=DEMO_KEY
    {
      "responseHeader":{
        "zkConnected":true,
        "status":0,
        "QTime":11,
        "params":{
          "q":"id:7112643",
          "fl":"id,access,artist,abstract,author,collection,collection_id,coverage,dataset,date,date_created,doi_url,format,handle_url,issue,language,publication_year,publisher,relation,source,specimen,series,subject,title,type,url,variety,volume",
          "start":"0",
          "sort":"id asc",
          "rows":"20",
          "wt":"javabin",
          "version":"2"}},
      "response":{"numFound":1,"start":0,"numFoundExact":true,"docs":[
          {
            "date":"0000",
            "subject":["COVID-19 (Disease)",
              "Economic aspects",
              "Electronic information resources",
              "Government policy",
              "Federal aid",
              "Rural development",
              "Rural health",
              "Economic assistance, American"],
            "language":["English"],
            "source":["USDA"],
            "title":"COVID-19 federal rural resource guide",
            "type":"text",
            "collection_id":"COLL00002",
            "variety":["COVID-19 (Disease)",
              "Economic aspects",
              "Electronic information resources",
              "Government policy",
              "Federal aid",
              "Rural development",
              "Rural health",
              "Economic assistance, American"],
            "id":"7112643",
            "specimen":"7112643",
            "coverage":["United States"],
            "handle_url":"https://handle.nal.usda.gov/10113/7112643",
            "author":["United States Department of Agriculture"],
            "artist":["United States Department of Agriculture"],
            "format":"text",
            "abstract":"USDA and its Federal partners have programs that can be used to provide immediate and long-term assistance to rural communities affected by the COVID-19 outbreak. These programs can support recovery efforts for rural residents, businesses and communities. This resource guide organizes funding opportunities identified in stimulus bills and other federal resources that can help support rural America.",
            "collection":"USDA publications",
            "url":["https://www.rd.usda.gov/sites/default/files/USDA_COVID-19_Fed_Rural_Resource_Guide.pdf"],
            "publication_year":"2020",
            "publisher":["United States Department of Agriculture"]}]
      },
      "highlighting":{
        "7112643":{}},
      "spellcheck":{
        "suggestions":[],
        "correctlySpelled":false,
        "collations":[]}}
    

    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
    
    curl https://api.nal.usda.gov/naldc/rest/search?query=corn&api_key=DEMO_KEY
    
    Or a fielded search:

    • id
    • abstract
    • artist
    • author
    • collection
    • collection_id
    • coverage
    • dataset
    • date
    • date_created
    • doi_url
    • format
    • handle_url
    • language
    • publication_year
    • publisher
    • relation
    • series
    • source
    • specimen
    • subject
    • title
    • type
    • variety

    • id
    • abstract
    • access
    • artist
    • author
    • collection
    • collection_id
    • coverage
    • dataset
    • date
    • date_created
    • doi_url
    • format
    • handle_url
    • issue
    • language
    • original_note
    • publication_year
    • publisher
    • relation
    • series
    • source
    • specimen
    • subject
    • title
    • type
    • url
    • variety
    • volume

    Two examples on how to use these fields are below:
    https://api.nal.usda.gov/naldc/rest/search?query=subject:corn&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, to specify a page length of 10:
    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, to specify 100 results per page:
    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 or XML. The default is JSON. This can be specified in the API request or sent in the request header: Content-Type.

    For example, to specify an XML format:
    https://api.nal.usda.gov/naldc/rest/search?query=corn&format=XML&api_key=DEMO_KEY