API Guides

Learn and Explore

The following sections provide details about working with various aspects of the NPS API. Before diving into these guides, be sure to register for an API key. And, if you have a question that isn't answered here, check out the FAQs.

Authentication


To retrieve data from the NPS API, you’ll need to sign up for an API key. This 40 character string will uniquely identify you. Every time you make a request from the NPS API, you’ll need to pass this key along with your request. If your request is properly formatted and your API key is valid, you’ll get data in return.

Ways to Pass Your API Key

Your API key may be passed in a few different ways.

HTTP Header

curl -H 'X-Api-Key: INSERT-API-KEY-HERE' 'https://developer.nps.gov/api/v1/parks?parkCode=acad'

GET Query Parameter

curl 'https://developer.nps.gov/api/v1/parks?parkCode=acad&api_key=INSERT-API-KEY-HERE'

HTTP Basic Auth Username

curl 'https://INSERT-API-KEY-HERE@developer.nps.gov/api/v1/parks?parkCode=acad'

Authentication Code Samples

The following code samples authenticate by passing the API key as part of the HTTP header.

PHP

<?php
// Get cURL resource
$curl = curl_init();
// Set options
$dataURL = 'https://developer.nps.gov/api/v1/parks?stateCode=me';
curl_setopt_array($curl, array(
CURLOPT_RETURNTRANSFER =--> true,
CURLOPT_URL => $dataURL,
CURLOPT_USERAGENT => $_SERVER['HTTP_USER_AGENT'],
CURLOPT_HTTPHEADER => array('Authorization: INSERT_API_KEY_HERE')
));
// Additional code would follow
?>

Python

import urllib.request, json
# Configure API request
endpoint = "https://developer.nps.gov/api/v1/parks?stateCode=me"
HEADERS = {"Authorization":"INSERT_API_KEY_HERE"}
req = urllib.request.Request(endpoint,headers=HEADERS)
# Additional code would follow
Top

Rate Limits

Limits are placed on the number of API requests you may make using your API key. Rate limits may vary by service, but the defaults are:

  • Hourly Limit: 1,000 requests per hour

For each API key, these limits are applied across all developer.nps.gov API requests. Exceeding these limits will lead to your API key being temporarily blocked from making further requests. The block will automatically be lifted by waiting an hour.

How Do I See My Current Usage?

You can check your current rate limit and usage details by inspecting the X-RateLimit-Limit and X-RateLimit-Remaining HTTP headers that are returned on every API response. For example, if an API has the default hourly limit of 1,000 requests, after making 2 requests, you will receive these HTTP headers in the response of the second request:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 998

Understanding Rate Limit Time Periods

Hourly Limit

The hourly counters for your API key reset on a rolling basis.

Example: If you made 500 requests at 10:15 am and 500 requests at 10:25 am, your API key would become temporarily blocked. This temporary block of your API key would cease at 11:15 am, at which point you could make 500 requests. At 11:25 am, you could then make another 500 requests.

Rate Limit Error Response

If your API key exceeds the rate limits, you will receive a response with an HTTP status code of 429 (Too Many Requests).

Top

Terms of Use

Please visit the Disclaimer page for information on using NPS data.

Top

Last updated: September 12, 2017