NPR ONE Api
The interface to our OAuth2 server
Please be aware that the required parameters are contingent on the grant_type that you select.
For the authorization_code grant type, you are required to pass in the code and redirect_uri parameters. service, username and password parameters will be ignored.
For the client_credentials grant type, you do not need to pass in any additional parameters beyond the basic requirements. code, redirect_uri, service, username and password parameters will be ignored.
For the device_code grant type, you are required to pass in the code parameter. redirect_uri, service, username and password parameters will be ignored.
For the password grant type, you are required to pass in the username and password parameters. If you are logging in via a social service, you should also pass in the service parameter. (In this case, the access token you receive from the social service will serve as both your username and password.) The code and redirect_uri parameters are ignored.
Third-party developers do not have access to this grant type.
For the refresh_token grant type, you are required to pass in the refresh_token parameter. The scope parameter can optionally be used to request a different set of scopes than were used in the original request, but it cannot contain any scopes that were not previously requested. If not specified, then scope will be set to whichever scopes were used for the original access token request. If trading in an old non-expiring access token for a refresh-enabled token, set the value of refresh_token to the access token value and token_type_hint must be set to access_token. code, redirect_uri, service, username and password parameters will be ignored.
The temporary_user and anonymous_user grant types are custom grant types created by NPR to suit our needs for functionality such as our "try-before-you-buy" experience. If you are a third-party developer, you will not have access to these grant types unless we have explicitly given you permission within our system.
For these grant types, you do not need to pass in any additional parameters beyond the basic requirements. code, redirect_uri, service, username and password parameters will be ignored.
If you are unsure of which grant type to select, assume that authorization_code is the one you want.
Note that at this time, refresh tokens are an opt-in feature; however, in the future, they will gradually transition to being opt-out, and ultimately required for all clients. Our general guidance at this time is that if this endpoint starts returning refresh tokens for you, you are responsible for implementing the code to handle them appropriately in accordance with the OAuth 2.0 spec. For more information about our gradual rollout of this feature, please contact the NPR One API team.
Request body
The type of grant the client is requesting
The client’s ID, required for all grant types.
The client’s secret, required for all grant types.
Required for authorization_code and device_code grant types. The authorization code from a successful call to /authorization/v2/authorize, or a device code from a successful call to /authorization/v2/device.
Required for authorization_code grant type. The requested redirect_uri.
Required for password grant type. The email address of an NPR user.
Required for password grant type. The password that matches the user specified with the username parameter.
If logging in via a social service, this parameter should be set. Only used for the password grant type.
Required for refresh_token grant type. A valid refresh token from a previous successful call to POST /authorization/v2/token.
Optionally used by the refresh_token grant type only. A space-separated list of scope(s) requested by the application.
A hint about the type of the token submitted for a new access and refresh token. If unspecified, the default value is assumed to be refresh_token.
Responses
A new token was successfully created
Body
The client credentials were invalid (any grant type), the user credentials were invalid (password grant type), the user has not yet logged in or has purposely denied the request (device_code grant type), or the authorization server denied the request.
Body
If the parameters passed to this endpoint are correct, it will redirect to npr.org/oauth2/login for the user to complete the sign-in.
Currently acceptable values for scope are any combination of the following:
identity.readonly- for read-only access to the Identity Serviceidentity.write- for write access to the Identity Servicelistening.readonly- for read-only access to the Listening Servicelistening.write- for write access to the Listening Servicelocalactivation- for all access to the Local Activation Service
It is generally suggested that you assume that you will need all of the current scopes in order to successfully implement an NPR One application.
If the parameters passed in are NOT correct and the client passed in a valid redirect_uri parameter, the request will be redirected to {{YOUR_REDIRECT_URI}}?error={{ERROR_TYPE}}&message={{ERROR_DESCRIPTION}}.
If the parameters passed are NOT correct and the client did not pass in a valid redirect_uri parameter, this endpoint will return the errors encoded as JSON objects (along with the corresponding HTTP status code – usually 400).
The latter is intended for development and debugging purposes – in a real-world situation, errors returned as JSON objects are irretrievable by the client application, and thus passing in a valid redirect_uri is critical even for the purpose of capturing errors.
If the user successfully logs in and authorizes the application, the request will be redirected to {{YOUR_REDIRECT_URI}}?code={{AUTHORIZATION_CODE}}&state={{CSRF_TOKEN}}
If the user DENIES the application, they will be redirected to {{YOUR_REDIRECT_URI}}?error=denied&message=The%20user%20has%20denied%20the%20login%20and%20access%20request&state={{CSRF_TOKEN}}.
This means that if your application flow requires a user to log in in order to proceed, it is up to you to give them the proper messaging explaining that the sign-in must be authorized in order to continue.
Finally, please do not confuse an authorization code with an access token. Once your app has completed this flow, you will still need to call POST /authorization/v2/token in order to swap the code for a valid access token.
Request parameters
The client’s ID
The client’s URL to redirect to if the authentication is approved
The type of response; currently, only code is supported
A space-separated list of scope(s) requested by the application
A CSRF token generated by the client, to be roundtripped through the request for added security
Responses
The correct parameters were passed in and we are redirecting to the authentication page; OR, a valid redirect_uri was supplied but there was another error, and the error type and message are embedded in the querystring.
Headers
The sign-in page to redirect to; most clients will process this redirect automatically.
Body
A bad request; generally, one or more parameters passed in were incorrect or missing. This error will only be shown if the client did not pass in a valid redirect_uri; otherwise, all errors will be returned as 302s to the supplied redirect_uri, with the error type and message embedded in the querystring.
The client credentials were invalid (i.e., the redirect_uri does not match what we have stored for this client) or the authorization server denied the request. This error will only be shown if the client did not pass in a valid redirect_uri; otherwise, all errors will be returned as 302s to the supplied redirect_uri, with the error type and message embedded in the querystring.
There was an unspecified server error. This error will only be shown if the client did not pass in a valid redirect_uri; otherwise, all errors will be returned as 302s to the supplied redirect_uri, with the error type and message embedded in the querystring.
The system is undergoing maintenance and we are unable to fulfill this request. This error will only be shown if the client did not pass in a valid redirect_uri; otherwise, all errors will be returned as 302s to the supplied redirect_uri, with the error type and message embedded in the querystring.
This flow should only be used by clients who cannot show a native webview or do not have advanced input controls. It is an alternative to GET /authorization/v2/authorize.
Third-party clients will need to use one or the other of these two endpoints, but they will generally not use both.
Request body
The client’s ID
The client’s secret key
A space-separated list of scope(s) requested by the application. Required for all untrusted clients; will be ignored for trusted clients.
Responses
We have generated a unique device code and user code. These will only be valid for the amount of time specified in the expires_in field; if the user does not complete the login process in that amount of time, the client will need to request a new set of codes.
Body
Our implementation follows the proposed IETF specification RFC-7009.
If your client application offers the ability to for a logged-in user to log out, and you have access to a long-lived
client_credentials token (i.e. you have generated one that you are storing securely for the lifetime of the entire app
install), we suggest (but do not require) that you call this endpoint and revoke the access token belonging to the
logged-in user as part of your logout process. If you do not already have a long-lived client_credentials token,
please don’t generate one just for the purposes of calling this endpoint.
If you are building a prototype application, we also recommend that you use this endpoint to clean up access tokens that you generate during the testing of your app and do not intend to reuse.
Note that revoking an access token will automatically revoke any refresh tokens associated with it, and vice-versa.
Request headers
A client_credentials access token from the same client application as the token being revoked. Should start with Bearer, followed by a space, followed by the token.
Request body
The access token or refresh token that the client wants to have revoked.
A hint about the type of the token submitted for revocation. If unspecified, the default value is assumed to be access_token.
Responses
The old token was successfully revoked
Body
The client associated with the access token in the header does not own the access token that this request is attempting to revoke.
Body
The entry point to user-specific information
Authentication
After a successful login, the client should send a GET call approximately once an hour to refresh the user data.
Request headers
Responses
Examples
GET /identity/v2/user HTTP/1.1
HTTP/1.1 200 OK
Content-Type: application/json
{
"version": "",
"href": "",
"links": {},
"attributes": {
"id": "",
"firstName": "",
"lastName": "",
"email": "",
"cohort": {
"id": "",
"name": "",
"directory": ""
},
"organizations": [
{
"id": "",
"displayName": "",
"call": "",
"city": "",
"logo": "",
"smallLogo": "",
"donationUrl": "",
"notif_org": [
""
]
}
],
"affiliations": [
{
"id": 1,
"title": "",
"rating": 1,
"href": "",
"daysSinceLastListen": 1,
"notif_following": [
""
],
"notif_rated": [
""
],
"following": true
}
]
}
}Authentication
Right now, only the primary station can be changed. Previously selected stations will not be deleted, but the new station will be moved to first in the array.
Request headers
Request body
A JSON-serialized array of station IDs
Responses
Authentication
This can and should only be used by clients who have access to the temporary_user grant type.
Third-party developers do not have access to this grant type by default, and will not need this endpoint.
Request parameters
The temporary user’s ID before the user registered or logged in
Request headers
Responses
Authentication
After a successful call, this returns a User document with an updated list of affiliations.
Request headers
Request body
A JSON-serialized object which contains data about a user affiliation such as the aggregation ID, affiliation rating, aggregation URL, days since last listen, and following status.
Responses
Audio recommendations tailored to a user’s preferences
{orgId}/recommendations{orgId}/categories/{category}/recommendations{aggId}/recommendationsAuthentication
These channels allow the user to specify a focus for the content returned in the recommendations endpoint.
Request parameters
If set to true, this call will return only channels that should be shown in the client’s Explore view
Request headers
Responses
A list of channels
Headers
The number of allowed requests in the current period
The number of remaining requests in the current period
The number of seconds left in the current period
Body
Examples
GET /listening/v2/channels HTTP/1.1
Authorization: Bearer 1234
HTTP/1.1 200 OK
Content-Type: application/json
{
"version": "",
"href": "",
"errors": [
null
],
"attributes": {
"defaultChannel": ""
},
"items": [
{
"version": "",
"href": "",
"errors": [
null
],
"attributes": {
"id": "",
"fullName": "",
"description": "",
"displayType": "default",
"emptyText": "",
"refreshRule": 1
},
"items": [
null
],
"links": {}
}
],
"links": {}
}{orgId}/recommendationsAuthentication
This endpoint provides a variety of details about an organization including various lists of recent audio items.
Path variables
ID of an organization, such as an NPR One station
Request headers
Responses
A list of up to three different categories of audio items from a specific organization
Headers
The number of allowed requests in the current period
The number of remaining requests in the current period
The number of seconds left in the current period
{orgId}/categories/{category}/recommendationsAuthentication
This endpoint provides a list of recommendations from a category of content from an organization.
Path variables
ID of an organization, such as an NPR One station
One of the three categories of content - newscast, story, or podcast
Request headers
Responses
A list of audio items from a category of content from an organization
Headers
The number of allowed requests in the current period
The number of remaining requests in the current period
The number of seconds left in the current period
Authentication
This endpoint is the main mechanism for providing feedback from the user to NPR about the recommendations that are obtained from GET /listening/v2/recommendations.
A fully-populated link to this endpoint is returned with each individual recommendation and is located in the AudioItemDocument under the links['recommendations'] object. The query parameters in this link should not be modified.
Be sure to copy and send back the entire ratings object (RatingData), as new fields may be added to it in the future.
This endpoint can return a blank JSON.doc or AudioItemDocument depending on the recommend=true|false parameter. The recommend=true flag allows this endpoint to both receive ratings and send back recommendations in the same call.
Request parameters
Determines the focus of the recommendations returned. Channel npr is recommended for most use cases.
If set to false, this call will return a blank document; otherwise it will return a new recommendation object
Request headers
Request body
A list of RatingData objects which contains data about ratings such as the id of the content, the rating value, elapsed time and more.
Responses
If the recommend param was set to true, this returns a list of audio items; otherwise, a blank document is returned.
Headers
The number of allowed requests in the current period
The number of remaining requests in the current period
The number of seconds left in the current period
Authentication
This endpoint returns a list of audio recommendations. It is designed to be used for an initial list of recommendations, and then GET /listening/v2/ratings?recommend=true should be used for subsequent requests for recommendations.
A fully-populated link to the ratings endpoint is returned with each individual recommendation and is located in the AudioItemDocument under the links['recommendations'] object. The query parameters in this link should not be modified.
Be sure to copy and send back the entire ratings object (RatingData), as new fields may be added to it in the future.
Request parameters
Determines the focus of the recommendations returned. Channel npr is recommended for most use cases.
This media was shared directly with the user; if provided, the service will add this recommendation to the top of the list
The user received a push notification about this media; if provided, the service will add this recommendation to the top of the list
Request headers
Responses
Authentication
This endpoint provides the list of recently-rated audio recommendations that the logged-in user has consumed. Some rated recommendations are filtered, such as sponsorship and donation.
Request headers
Responses
Authentication
Gets the most recently played promo for which the user has neither tapped through the promo or listened to the target story.
Request headers
Responses
{aggId}/recommendationsAuthentication
This endpoint provides a list of recent audio items associated with the aggregation along with metadata about the aggregation.
Path variables
ID of an aggregation such as a program or podcast
Request parameters
The result to start with. Allows paging through the episodes of a podcast or program, with the default, startNum=0, being the most recent episode
Request headers
Responses
A list of audio items from the specified aggregation
Headers
The number of allowed requests in the current period
The number of remaining requests in the current period
The number of seconds left in the current period
Authentication
In the schema shown below, SearchItemDocument is not an actual type of returned object; the object returned by a search will be either an AggregationAudioItemListDocument or an AudioItemDocument.
Request parameters
Search terms to search on; can include URL-encoded punctuation
Request headers
Responses
A list of audio and aggregation items matching the search query
Headers
The number of allowed requests in the current period
The number of remaining requests in the current period
The number of seconds left in the current period
Body
Connects users to their local stations
Authentication
This will send a station-specific donation email to the logged-in user.
Request headers
Responses
On success only a blank document
Headers
The number of allowed requests in the current period
The number of remaining requests in the current period
The number of seconds left in the current period
Body
Sponsorship for non-NPR One client applications
Not for use by NPR One clients (for whom sponsorship is already integrated into the Listening Service), this endpoint is designed to be used by our other client applications to request sponsorship on behalf of a user. Sponsorship units are returned in the form of DAAST XML. It is worth noting that this endpoint attempts to always return XML, even in the case of exceptions.
The default behavior of this endpoint is asynchronous; on an initial request, a call to our external sponsorship provider is placed on a queue, which is typically processed within 3 minutes. Once the sponsorship call is received and processed, the returned sponsorship units are placed in a cache on our server for the current user. Subsequent calls to this endpoint will return DAAST sponsorship units from this cache until tracking information is submitted, which removes the ad from the cache and will automatically request additional ads asynchronously if there are fewer than a certain number remaining in the cache.
For development purposes, it’s worth noting that there is currently no way to clear a user’s cache without submitting some form of tracking.
Request parameters
Whether to force a synchronous call to our external sponsorship provider; the default behavior is asynchronous.
How many sponsorship units to request in one call; if left unspecified, the default behavior is to return only 1.
Request headers
Responses
Request completed successfully; a DAAST XML document is returned. Note that this response will only be returned if either force=true was passed in the querystring, or a call to get sponsorship was previously made, and ads now exist in the cache for this user; otherwise, the 202 response is returned.
Request accepted. Check back later for actual ads.
A bad request; generally, one or more parameters passed in were incorrect or missing
A server error
Not for use by NPR One clients (for whom sponsorship is already integrated into the Listening Service), this endpoint is designed to be used by our other client applications to submit tracking information for sponsorship units obtained from the GET /sponsorship/v2/ads endpoint.
The tracking information should be submitted in the body of the request in the form of a JSON object following the Collection.Doc+JSON specification.
Request headers
Request body
A JSON object representing sponsorship tracking data to submit to our external provider.
Allows clients to look up information for organizations that partner with NPR, including stations and third-party content providers.
{orgId}{orgId}This endpoint retrieves information about a given organization, based on its numeric ID, which is consistent across all of NPR’s APIs. NPR partners, as defined by this service, include member stations as well as third-party content providers. A successful request will return a document with metadata for the requested organization, including branding assets such as links to the organization’s logo and homepage, if such links are available.
Path variables
The numeric ID of an organization
Request headers
Responses
A document describing the organization with the given ID.
Headers
The number of allowed requests in the current period
The number of remaining requests in the current period
The number of seconds left in the current period
Body
Allows clients to look up NPR member station information
{stationId}This endpoint has two main use cases:
- If no query parameters passed in, it returns a list of stations that are geographically closest to the calling client (based on GeoIP information)
- If one or more query parameters are passed in, it performs a search of NPR stations that match those search criteria (not taking into account the client’s physical location)
Clients wanting to implement a ‘Change Station’ UI should use this endpoint to power their search. In most cases, you’ll want to build a search interface that uses one of the 3 provided schemas: lat and lon (using e.g. the HTML5 Geolocation API), city and state, or the generic q query which can accept a station name, call letters, network name, or zip code. Technically speaking, q can also take in either a city name or a state name, but using the city and state parameters together will yield more accurate geographic search results than q={cityName}.
The lat and lon query parameters should always be passed in together (otherwise the API will return a 400 error), and if included in the query, they will take precedence over any other search criteria; that is, lat and lon will do a purely geographic search and not take into account q, city or state.
Similarly, city and/or state will take precedence over (and ignore) q.
If clients want to be able to offer multiple types of searches (e.g. ‘Search for a station name, city or zipcode’) using a single search input form, q should be used. But again, be aware that using city and state together will yield more accurate search results than q={cityName}.
Request parameters
Search terms to search on; can be a station name, network name, call letters, or zipcode
A city to look for stations from; intended to be paired with state
A state to look for stations from (using the 2-letter abbreviation); intended to be paired with city
A latitude value from a geographic coordinate system; only works if paired with lon
A longitude value from a geographic coordinate system; only works if paired with lat
Request headers
Responses
A list of one or more stations matching the search query
Headers
The number of allowed requests in the current period
The number of remaining requests in the current period
The number of seconds left in the current period
Body
{stationId}This endpoint retrieves information about a given station, based on its numeric ID, which is consistent across all of NPR’s APIs.
A typical use case for this data is for clients who want to create a dropdown menu, modal/pop-up or dedicated page displaying more information about the station the client is localized to, including, for example, links to the station’s homepage and donation (pledge) page.
Path variables
The numeric ID of a station
Request headers
Responses
A document describing the station with the given ID
Headers
The number of allowed requests in the current period
The number of remaining requests in the current period
The number of seconds left in the current period
Body
A Collection.doc+JSON representation of an error result from an API call
Object; see description of a user object below
An array of audio recommendations with additional metadata about the aggregation they are associated with
A link to audio files for the item
An image, along with metadata for display
An individual link from a list of links
An array of a certain category of audio recommendations from a provider
a variety of details about an organization including various lists of recent audio items
An array of aggregation or audio recommendations
A search result, which is either an AggregationAudioItemListDocument or an AudioItemDocument
All the information needed for the Sponsorship Service to send back tracking information to our external sponsorship provider
Please visit <a href='http://www.iab.net/DAAST' target='_blank'>http://www.iab.net/DAAST</a> for more information on the DAAST XML specification.
All information relevant to a user who has requested sponsorship or submitted tracking information
An associative array of brand-related metadata for this station
Metadata about the network, if this station is part of a network
Metadata about the top-level organization in the network, if this station is part of a network
Metadata about a tier 2 organization in the network, if this station is part of a network
A link related to the station
A link to a web page, logo, or audio file related to the branding of the station
A link to an audio stream related to the station
A link to an audio podcast or podcast feed related to the station
A link to a pledge page for the station
A link to miscellaneous related content for the station; these typically are not present, and clients should generally not need to use these
A collection of stations close to you or filtered by search criteria
Determines the focus of the recommendations returned. Channel npr is recommended for most use cases.
Your access token from the Authorization Service. Should start with Bearer, followed by a space, followed by the token.
A device-specific advertising identifier, if possible. Apple’s IDFA is an example.
A bad request; generally, one or more parameters passed in were incorrect or missing
Body
The client credentials were invalid or the authorization server denied the request.
Body
A server error
Body
The system is undergoing maintenance and we are unable to fulfill this request. Look for a Retry-After header to see the predicted time the system will be back up.
Headers
The predicted time the system will be back up
Body
A bad request; generally, one or more parameters passed in were incorrect or missing
Headers
The number of allowed requests in the current period
The number of remaining requests in the current period
The number of seconds left in the current period
Body
The client is not authorized to complete this request. Check to ensure a valid access token was passed in the headers.
Body
The resource with the requested ID could not be found, and the server was unable to complete the request.
Headers
The number of allowed requests in the current period
The number of remaining requests in the current period
The number of seconds left in the current period
Body
The client has exceeded the number of daily calls as per their rate limit. For now, this only applies to prototype applications and untrusted clients. Trusted clients will never be rate-limited, nor will any production apps.
Headers
The number of allowed requests in the current period
The number of remaining requests in the current period
The number of seconds left in the current period
Body
A server error
Headers
The number of allowed requests in the current period
The number of remaining requests in the current period
The number of seconds left in the current period
Body
The system is undergoing maintenance and we are unable to fulfill this request. Look for a Retry-After header to see the predicted time the system will be back up.
Headers
The predicted time the system will be back up
Body
The request was successful
Headers
The number of allowed requests in the current period
The number of remaining requests in the current period
The number of seconds left in the current period
Body
A list of audio items (recommendations)
Headers
The number of allowed requests in the current period
The number of remaining requests in the current period
The number of seconds left in the current period