@datafire/npr
Client library for NPR One API Reference
Installation and Usage
npm install --save @datafire/npr
let npr = require('@datafire/npr').create({
access_token: "",
refresh_token: "",
client_id: "",
client_secret: "",
redirect_uri: ""
});
.then(data => {
console.log(data);
});
Description
NPR One is a smart application that brings the best of NPR and Member Station programming, newscasts, podcasts, and stories together to create a new experience for listening. It provides an editor-curated and localized mobile listening experience based on the content the listener chooses, likes, shares, and enjoys. The API provides all of the content and customization in a simple, structured way that is easy for application developers to implement.
Actions
oauthCallback
Exchange the code passed to your redirect URI for an access_token
npr.oauthCallback({
"code": ""
}, context)
Input
- input
object
- code required
string
- code required
Output
- output
object
- access_token
string
- refresh_token
string
- token_type
string
- scope
string
- expiration
string
- access_token
oauthRefresh
Exchange a refresh_token for an access_token
npr.oauthRefresh(null, context)
Input
This action has no parameters
Output
- output
object
- access_token
string
- refresh_token
string
- token_type
string
- scope
string
- expiration
string
- access_token
getAuthorizationPage
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 Service -
identity.write
- for write access to the Identity Service -
listening.readonly
- for read-only access to the Listening Service -
listening.write
- for write access to the Listening Service -
localactivation
- 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.
npr.getAuthorizationPage({
"client_id": "",
"redirect_uri": "",
"response_type": "",
"scope": "",
"state": ""
}, context)
Input
- input
object
- client_id required
string
: The client's ID - redirect_uri required
string
: The client's URL to redirect to if the authentication is approved - response_type required
string
(values: code): The type of response; currently, onlycode
is supported - scope required
string
: A space-separated list of scope(s) requested by the application - state required
string
: A CSRF token generated by the client, to be roundtripped through the request for added security
- client_id required
Output
Output schema unknown
generateDeviceCode
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.
npr.generateDeviceCode({
"client_id": "",
"client_secret": ""
}, context)
Input
- input
object
- client_id required
string
: The client's ID - client_secret required
string
: The client's secret key - scope
string
: A space-separated list of scope(s) requested by the application. Required for all untrusted clients; will be ignored for trusted clients.
- client_id required
Output
- output DeviceCodeData
createToken
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. If you are a third-party developer, you are also required to provide the scope
parameter; see the documentation for GET /authorization/v2/authorize
for possible values. 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. 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, if you are a third-party developer, you are required to provide the scope
parameter; see the documentation for GET /authorization/v2/authorize
for possible values. code
, redirect_uri
, service
, username
and password
parameters will be ignored.
The third_party
grant type is another custom grant type created by NPR to handle login via third-party providers such as Facebook and Google. If you are a third-party developer, you will not have access to this grant types unless we have explicitly given you permission within our system.
For this grant type, you are required to pass in the service
and token
parameters. If you are a third-party developer, you are also required to provide the scope
parameter; see the documentation for GET /authorization/v2/authorize
for possible values. The code
and redirect_uri
parameters are 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.
npr.createToken({
"grant_type": "",
"client_id": "",
"client_secret": ""
}, context)
Input
- input
object
- grant_type required
string
(values: authorization_code, client_credentials, device_code, password, refresh_token, temporary_user, anonymous_user, third_party): The type of grant the client is requesting - client_id required
string
: The client's ID, required for all grant types. - client_secret required
string
: The client's secret, required for all grant types. - code
string
: Required forauthorization_code
anddevice_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
. - redirect_uri
string
: Required forauthorization_code
grant type. The requested redirect_uri. - username
string
: Required forpassword
grant type. The email address of an NPR user. - password
string
: Required forpassword
grant type. The password that matches the user specified with the username parameter. - service
string
(values: facebook, google, microsoft, janrain, comcast): Required forthird_party
grant type. The name of the third-party login provider. - refresh_token
string
: Required forrefresh_token
grant type. A valid refresh token from a previous successful call toPOST /authorization/v2/token
. - scope
string
: Required for third-party developers using thedevice_code
,temporary_user
, andthird_party
grant types. Optionally used by therefresh_token
grant type. A space-separated list of scope(s) requested by the application. - token_type_hint
string
(values: access_token, refresh_token): A hint about the type of the token submitted for a new access and refresh token. If unspecified, the default value is assumed to berefresh_token
.
- grant_type required
Output
- output AccessTokenData
revokeToken
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.
npr.revokeToken({
"Authorization": "",
"token": ""
}, context)
Input
- input
object
- Authorization required
string
: Aclient_credentials
access token from the same client application as the token being revoked. Should start withBearer
, followed by a space, followed by the token. - token required
string
: The access token or refresh token that the client wants to have revoked. - token_type_hint
string
(values: access_token, refresh_token): A hint about the type of the token submitted for revocation. If unspecified, the default value is assumed to beaccess_token
.
- Authorization required
Output
- output
object
: An empty JSON object
postFollowing
After a successful call, this returns a User document with an updated list of affiliations.
npr.postFollowing({
"Authorization": "",
"body": null
}, context)
Input
- input
object
- Authorization required
string
: Your access token from the Authorization Service. Should start withBearer
, followed by a space, followed by the token. - body required Affiliation
- Authorization required
Output
- output UserDocument
updateStations
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.
npr.updateStations({
"Authorization": ""
}, context)
Input
- input
object
- Authorization required
string
: Your access token from the Authorization Service. Should start withBearer
, followed by a space, followed by the token. - body
array
- items
integer
- items
- Authorization required
Output
- output UserDocument
getUser
After a successful login, the client should send a GET
call approximately once an hour to refresh the user data.
npr.getUser({
"Authorization": ""
}, context)
Input
- input
object
- Authorization required
string
: Your access token from the Authorization Service. Should start withBearer
, followed by a space, followed by the token.
- Authorization required
Output
- output UserDocument
inheritFromTempUser
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.
npr.inheritFromTempUser({
"Authorization": "",
"temp_user": 0
}, context)
Input
- input
object
- Authorization required
string
: Your access token from the Authorization Service. Should start withBearer
, followed by a space, followed by the token. - temp_user required
integer
: The temporary user's ID before the user registered or logged in
- Authorization required
Output
- output UserDocument
getAggRecommendations
This endpoint provides a list of recent audio items associated with the aggregation along with metadata about the aggregation.
npr.getAggRecommendations({
"aggId": 0,
"Authorization": ""
}, context)
Input
- input
object
- aggId required
integer
: ID of an aggregation such as a program or podcast - Authorization required
string
: Your access token from the Authorization Service. Should start withBearer
, followed by a space, followed by the token. - startNum
integer
: 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
- aggId required
Output
getChannels
These channels allow the user to specify a focus for the content returned in the recommendations endpoint.
npr.getChannels({
"Authorization": ""
}, context)
Input
- input
object
- Authorization required
string
: Your access token from the Authorization Service. Should start withBearer
, followed by a space, followed by the token. - exploreOnly
boolean
: If set totrue
, this call will return only channels that should be shown in the client'sExplore
view
- Authorization required
Output
- output ChannelsDocument
getHistory
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.
npr.getHistory({
"Authorization": ""
}, context)
Input
- input
object
- Authorization required
string
: Your access token from the Authorization Service. Should start withBearer
, followed by a space, followed by the token.
- Authorization required
Output
- output AudioItemListDocument
getOrganizationCategory
This endpoint provides a list of recommendations from a category of content from an organization.
npr.getOrganizationCategory({
"orgId": 0,
"category": "",
"Authorization": ""
}, context)
Input
- input
object
- orgId required
integer
: ID of an organization, such as an NPR One station - category required
string
(values: newscast, story, podcast): One of the three categories of content - newscast, story, or podcast - Authorization required
string
: Your access token from the Authorization Service. Should start withBearer
, followed by a space, followed by the token.
- orgId required
Output
getOrganizationOverview
This endpoint provides a variety of details about an organization including various lists of recent audio items.
npr.getOrganizationOverview({
"orgId": 0,
"Authorization": ""
}, context)
Input
- input
object
- orgId required
integer
: ID of an organization, such as an NPR One station - Authorization required
string
: Your access token from the Authorization Service. Should start withBearer
, followed by a space, followed by the token.
- orgId required
Output
- output OrganizationOverviewDocument
getPromo
Gets the most recently played promo for which the user has neither tapped through the promo or listened to the target story.
npr.getPromo({
"Authorization": ""
}, context)
Input
- input
object
- Authorization required
string
: Your access token from the Authorization Service. Should start withBearer
, followed by a space, followed by the token.
- Authorization required
Output
- output AudioItemListDocument
postRating
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.
npr.postRating({
"Authorization": "",
"body": []
}, context)
Input
- input
object
- Authorization required
string
: Your access token from the Authorization Service. Should start withBearer
, followed by a space, followed by the token. - X-Advertising-ID
string
: A device-specific advertising identifier, if possible. Apple's IDFA is an example. - channel
string
(values: npr, followed, recommended, emailstories, emailprograms, lapsedusersemail, ongoing email, newscasts, shows): Determines the focus of the recommendations returned. Channelnpr
is recommended for most use cases. - recommend
boolean
: If set tofalse
, this call will return a blank document; otherwise it will return a new recommendation object - body required
array
- items RatingData
- Authorization required
Output
- output AudioItemListDocument
getRecommendations
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.
npr.getRecommendations({
"Authorization": ""
}, context)
Input
- input
object
- Authorization required
string
: Your access token from the Authorization Service. Should start withBearer
, followed by a space, followed by the token. - X-Advertising-ID
string
: A device-specific advertising identifier, if possible. Apple's IDFA is an example. - channel
string
(values: npr, followed, recommended, emailstories, emailprograms, lapsedusersemail, ongoing email, newscasts, shows): Determines the focus of the recommendations returned. Channelnpr
is recommended for most use cases. - sharedMediaId
string
: This media was shared directly with the user; if provided, the service will add this recommendation to the top of the list - notifiedMediaId
string
: The user received a push notification about this media; if provided, the service will add this recommendation to the top of the list
- Authorization required
Output
- output AudioItemListDocument
getSearchRecommendations
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.
npr.getSearchRecommendations({
"Authorization": "",
"searchTerms": ""
}, context)
Input
- input
object
- Authorization required
string
: Your access token from the Authorization Service. Should start withBearer
, followed by a space, followed by the token. - searchTerms required
string
: Search terms to search on; can include URL-encoded punctuation
- Authorization required
Output
- output SearchListDocument
sendDonationEmail
This will send a station-specific donation email to the logged-in user.
npr.sendDonationEmail({
"Authorization": ""
}, context)
Input
- input
object
- Authorization required
string
: Your access token from the Authorization Service. Should start withBearer
, followed by a space, followed by the token.
- Authorization required
Output
- output CollectionDocument
getAds
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.
npr.getAds({
"Authorization": ""
}, context)
Input
- input
object
- Authorization required
string
: Your access token from the Authorization Service. Should start withBearer
, followed by a space, followed by the token. - X-Advertising-ID
string
: A device-specific advertising identifier, if possible. Apple's IDFA is an example. - forceResult
boolean
: Whether to force a synchronous call to our external sponsorship provider; the default behavior is asynchronous. - adCount
integer
: How many sponsorship units to request in one call; if left unspecified, the default behavior is to return only 1.
- Authorization required
Output
- output DAASTXml
receiveAdTracking
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.
npr.receiveAdTracking({
"Authorization": "",
"body": null
}, context)
Input
- input
object
- Authorization required
string
: Your access token from the Authorization Service. Should start withBearer
, followed by a space, followed by the token. - X-Advertising-ID
string
: A device-specific advertising identifier, if possible. Apple's IDFA is an example. - body required UserAdDocument
- Authorization required
Output
Output schema unknown
searchStations
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}
.
npr.searchStations({
"Authorization": ""
}, context)
Input
- input
object
- Authorization required
string
: Your access token from the Authorization Service. Should start withBearer
, followed by a space, followed by the token. - q
string
: Search terms to search on; can be a station name, network name, call letters, or zipcode - city
string
: A city to look for stations from; intended to be paired withstate
- state
string
: A state to look for stations from (using the 2-letter abbreviation); intended to be paired withcity
- lat
number
: A latitude value from a geographic coordinate system; only works if paired withlon
- lon
number
: A longitude value from a geographic coordinate system; only works if paired withlat
- Authorization required
Output
- output StationListDocument
getStationById
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.
npr.getStationById({
"Authorization": "",
"stationId": 0
}, context)
Input
- input
object
- Authorization required
string
: Your access token from the Authorization Service. Should start withBearer
, followed by a space, followed by the token. - stationId required
integer
: The numeric ID of a station
- Authorization required
Output
- output StationDocument
Definitions
AbstractCDocLink
- AbstractCDocLink
- href required
string
: The link to be followed - content-type required
string
: The MIME type of the response of this link
- href required
AbstractLink
- AbstractLink
object
- href required
string
: The link to be followed
- href required
AccessTokenData
- AccessTokenData
object
- access_token required
string
: The access token to use for all future calls - expires_in required
integer
: The remaining lifetime of the access token (in seconds) - refresh_token
string
: The refresh token that can be used to obtain a new access token if the old one expires; if a refresh token is returned, it is the client's responsibility to securely cache it for future use. - token_type required
string
(values: Bearer, MAC): Identifies the type of token returned. At this time, this field always has the valueBearer
.
- access_token required
AdTrackingData
- AdTrackingData
object
: All the information needed for the Sponsorship Service to send back tracking information to our external sponsorship provider- adId required
string
: The DAAST Ad nodeid
attribute value, (e.g. AdswizzAd12345) - event required
string
(values: start, firstQuartile, midpoint, thirdQuartile, complete): The user-interaction event to submit tracking for
- adId required
AdTrackingDocument
- AdTrackingDocument: All the information needed for the Sponsorship Service to send back tracking information to our external sponsorship provider
- attributes required
object
- errors required
array
: A list of encountered errors, ignored on POST, PUT- items
null
- items
- href required
string
: A URL representation of the resource; should generally be ignored by clients unless noted otherwise - items required
array
- items
null
- items
- links required
object
- version required
string
: The version of the Collection.Doc+JSON spec being used - attributes AdTrackingData
- items
array
: Not used- items
null
- items
- attributes required
AdXml
- AdXml
object
- InLine InLineXml
- id
string
Affiliation
- Affiliation
object
: A program (aggregation) that a given user has shown an affiliation with- daysSinceLastListen
integer
: The number of days since a user last listened to a story from this aggregation. Absent if user never listened to the aggregation. - following required
boolean
: Whether or not the user is following the aggregation. When changing affiliation status, the client is expected to toggle this value and then send the entire object back. - href required
string
: A link to more details about the program from the NPR Story API - id required
integer
: A unique identifier for the aggregation (program) - notif_following
array
: The topic in Firebase Cloud Messaging to which the device should subscribe if it supports notifications and the user wants notifications about the podcasts they follow.- items
string
- items
- notif_rated
array
: The topic in Firebase Cloud Messaging to which the device should subscribe if it supports notifications and the user wants notifications about the podcasts they have highly rated.- items
string
- items
- rating
number
: The user's average rating for this affiliation on a scale of 0-1. Absent if user never listened to the aggregation. - title
string
: The title for the aggregation (program)
- daysSinceLastListen
AggregationAudioItemListDocument
- AggregationAudioItemListDocument: An array of audio recommendations with additional metadata about the aggregation they are associated with
- attributes required
object
- errors required
array
: A list of encountered errors, ignored on POST, PUT- items
null
- items
- href required
string
: A URL representation of the resource; should generally be ignored by clients unless noted otherwise - items required
array
- items
null
- items
- links required
object
- version required
string
: The version of the Collection.Doc+JSON spec being used - attributes AggregationData
- items
array
: An array of Audio Items (recommendations)- items AudioItemDocument
- links AggregationLinks
- attributes required
AggregationData
- AggregationData
object
- affiliation required
string
: A unique identifier for the aggregation - affiliationMeta Affiliation
- description
string
: A short description or teaser - station
string
: The producer of this aggregation - title required
string
: The title of this aggregation - type required
string
(values: aggregation): The type of list returned; will always beaggregation
; useful for parsing search results
- affiliation required
AggregationLinks
- AggregationLinks
object
AudioItemData
- AudioItemData
object
- album
string
: Album information associated with the media - artist
string
: The artist associated with the media - audioTitle
string
: For first-party client use only - button
string
: The text contents of an action button displayed on the client - date
string
: The publication date in ISO-8601 format - description
string
: A short description or teaser - duration
integer
: The length of the audio content in seconds - expires
string
: The media's expiration date in ISO-8601 format - geofence Geofence
- label
string
: The record label associated with the media - organization RecommendationOrganization
- primary
boolean
: Whether the audio is the primary audio of the story to which it is associated - program
string
: The program associated with this media - provider
string
: The name of the organization providing this media - rating required RatingData
- rationale required
string
: A short summary of why this content was recommended - skippable required
boolean
: Whether the client should allow this content to be skipped - slug
string
: A tag or category for this media - song
string
: The song title associated with the media - title required
string
: The title of this media - type required
string
(values: audio, sponsorship, stationId, intro, donate, featureCardInformational, featureCardNotification, featureCardPromotion, featureCardExternalLink, featureCardAsyncRequest): Help determine how content is displayed; for more information, see our design guidelines - uid required
string
: The media ID (for use in ratings objects) - unavailableText
string
: The text contents to be displayed on the client if no media URLs are available
- album
AudioItemDocument
- AudioItemDocument
- attributes required
object
- errors required
array
: A list of encountered errors, ignored on POST, PUT- items
null
- items
- href required
string
: A URL representation of the resource; should generally be ignored by clients unless noted otherwise - items required
array
- items
null
- items
- links required
object
- version required
string
: The version of the Collection.Doc+JSON spec being used - attributes AudioItemData
- items
array
: Not used- items
null
- items
- links AudioItemLinks
- attributes required
AudioItemLinks
- AudioItemLinks
object
- action
array
: One or more links to be trigged by user actions, usually when a button is clicked- items OtherLink
- audio
array
: One or more links to audio files for the item- items AudioLink
- image
array
: One or more links to an image, along with metadata for display- items ImageLink
- onramps
array
: One or more shareable links for the item- items OtherLink
- ratings
array
: This is an alternate URL to use to POST the ratings JSON. Difference between this and 'recommendations' is that 'ratings' will NOT return back recommendations of audio to play next.- items OtherLink
- recommendations
array
: This is the URL that should be POSTed with the ratings JSON when this audio starts to play- items OtherLink
- up
array
: One or more links to more details about the program or podcast with which this item is associated- items OtherLink
- web
array
: One or more links to a web page for the item- items OtherLink
- action
AudioItemListDocument
- AudioItemListDocument
- attributes required
object
- errors required
array
: A list of encountered errors, ignored on POST, PUT- items
null
- items
- href required
string
: A URL representation of the resource; should generally be ignored by clients unless noted otherwise - items required
array
- items
null
- items
- links required
object
- version required
string
: The version of the Collection.Doc+JSON spec being used - attributes
object
: Not used - items
array
: An array of Audio Items (recommendations)- items AudioItemDocument
- links
object
: Not used
- attributes required
AudioLink
- AudioLink: A link to audio files for the item
- href required
string
: The link to be followed - content-type required
string
(values: audio/mp3, audio/aac, audio/3gp, application/vnd.apple.mpegurl, audio/x-ms-wax): The MIME type of the response of this link; note that the enumerated list of possible values is not exhaustive and other MIME types could occur. The list should be treated as examples, rather than absolutes.
- href required
Brand
- Brand
object
: Branding information for the organization- band
string
: The radio band for the organization if they are a station (AM or FM) - call required
string
: The call letter for the organization if they are a station - frequency
string
: The radio frequency for the organization if they are a station - marketCity required
string
: The market city for the organization - marketState
string
: The market state for the organization - name required
string
: The name of the organization - tagline
string
: The tagline for the organization
- band
CategoryData
- CategoryData
object
- displayType
string
(values: default, show, playable, newscast): How clients should display this channel in the station profile view - orgId required
integer
: The unique identifier for the organization - title required
string
: The title of this category - type required
string
: The type of list returned; will always becategory
- displayType
CategoryLinks
- CategoryLinks
object
- more
array
: One or more links to more episodes for the aggregation- items OtherLink
- more
ChannelData
- ChannelData
object
- description required
string
: A longer description of what this channel focuses on - displayType
string
(values: default, show, playable, newscast): How clients should display this channel in the explore view - emptyText
string
: Text for clients to display when the channel contains no recommendations - fullName required
string
: A short description of what this channel focuses on - id required
string
: The actual value that should be sent - refreshRule
integer
: In the explore view of a client, this field indicates how this channel should be refreshed. This is an experimental field and subject to change, but for now zero indicates the client should refresh this channel every time a START rating is sent for a type=audio recommendation, while a 1 would indicate it can be refreshed much less often, such as on a 30 minute timer. 2 would indicate even less time to update, say every hour. We are still experimenting on the number of rules necessary and the best implementation for each type of rule.
- description required
ChannelDocument
- ChannelDocument
- attributes required
object
- errors required
array
: A list of encountered errors, ignored on POST, PUT- items
null
- items
- href required
string
: A URL representation of the resource; should generally be ignored by clients unless noted otherwise - items required
array
- items
null
- items
- links required
object
- version required
string
: The version of the Collection.Doc+JSON spec being used - attributes ChannelData
- items
array
: Not used- items
null
- items
- links
object
: Not used
- attributes required
ChannelsData
- ChannelsData
object
- defaultChannel
string
: The default channel NPR recommends
- defaultChannel
ChannelsDocument
- ChannelsDocument
- attributes required
object
- errors required
array
: A list of encountered errors, ignored on POST, PUT- items
null
- items
- href required
string
: A URL representation of the resource; should generally be ignored by clients unless noted otherwise - items required
array
- items
null
- items
- links required
object
- version required
string
: The version of the Collection.Doc+JSON spec being used - attributes ChannelsData
- items
array
: The list of individual channels- items ChannelDocument
- links
object
: Not used
- attributes required
Cohort
- Cohort
object
: An experimental grouping for User Experience A/B Testing- directory
string
: For internal use only; represents the current configuration file being used by the Listening Service - id required
string
: A short ID for this cohort; ignored on a PUT - name required
string
: A text string identifying the cohort, useful for metrics; ignored on a PUT
- directory
CollectionDocument
- CollectionDocument
object
: Base Collection.Doc+JSON output- attributes required
object
- errors required
array
: A list of encountered errors, ignored on POST, PUT- items
null
- items
- href required
string
: A URL representation of the resource; should generally be ignored by clients unless noted otherwise - items required
array
- items
null
- items
- links required
object
- version required
string
: The version of the Collection.Doc+JSON spec being used
- attributes required
CompanionXml
- CompanionXml
object
- CompanionClickThrough
string
- StaticResource StaticResourceXml
- TrackingEvents
array
- items TrackingXml
- height
integer
- id
integer
- width
integer
- CompanionClickThrough
CreativeXml
- CreativeXml
object
- CompanionAds
array
- items CompanionXml
- Linear LinearXml
- id
integer
- sequence required
integer
- CompanionAds
DAASTXml
- DAASTXml
object
: Please visit http://www.iab.net/DAAST for more information on the DAAST XML specification.- Ad AdXml
- version required
string
DeviceCodeData
- DeviceCodeData
object
- device_code required
string
: 40-character code for the device to input into the /token endpoint, not for display to the user - expires_in required
integer
: The number of seconds for which this set of codes will be valid, after which they will be purged - interval required
integer
: The number of seconds the client application should maintain between requests to the /token endpoint - user_code required
string
: 6-character alphanumeric code for the user to enter at http://npr.org/device, to be displayed by the client application - verification_uri required
string
: The URL where the user should input their code, to be displayed by the client application
- device_code required
Error
- Error
object
: A serialized version of any error encountered when processing this request- code required
integer
: The error code - debug
string
: Additional debug information if debug mode is turned on - text
string
: The error description
- code required
ErrorDocument
- ErrorDocument: A Collection.doc+JSON representation of an error result from an API call
- attributes required
object
- errors required
array
: A list of encountered errors, ignored on POST, PUT- items
null
- items
- href required
string
: A URL representation of the resource; should generally be ignored by clients unless noted otherwise - items required
array
- items
null
- items
- links required
object
- version required
string
: The version of the Collection.Doc+JSON spec being used - attributes
object
: Ignore; will be empty for errors - errors
array
: A list of encountered errors, ignored on POST, PUT- items Error
- items
array
: Ignore; will be empty for errors- items
null
- items
- links
object
: Ignore; will be empty for errors
- attributes required
ErrorXmlDocument
- ErrorXmlDocument
object
: One or more errors represented in a DAAST XML document- error required
array
- items
string
: An individual error, presented in XML format
- items
- version required
string
- error required
Geofence
- Geofence
object
: The geographic restrictions that should be applied by the client before playing this media- countries required
array
: The list of countries as ISO 3166-1 abbreviations in which this media should be available if restricted is true- items
string
- items
- restricted required
boolean
: Whether any geographic restrictions should be applied
- countries required
HALDocument
- HALDocument
object
: Base HAL output- _links required
object
- _links required
ImageLink
- ImageLink: An image, along with metadata for display
- href required
string
: The link to be followed - content-type required
string
(values: image/jpeg, image/png, image/gif): The MIME type of the response of this link; note that the enumerated list of possible values is not exhaustive and other MIME types could occur. The list should be treated as examples, rather than absolutes. - image
string
: A unique identifier for the image - producer
string
: The producer of the image; should be used for properly attributing the image when it exists - provider
string
: The provider of the image; should be used for properly attributing the image when it exists - rel
string
(values: logo_square, icon, wide, standard, square, enlargement, custom): The crop type or intended display style/size; note that the enumerated list of possible values is not exhaustive and other values could occur. The list should be treated as examples, rather than absolutes.
- href required
ImpressionXml
- ImpressionXml
string
- id required
integer
- id required
InLineXml
- InLineXml
object
- AdSystem
string
- AdTitle
string
- Category
string
- Creatives
array
- items CreativeXml
- Description
string
- Extensions
array
- items
string
- items
- Impression
array
- items ImpressionXml
- AdSystem
LinearXml
- LinearXml
object
- Duration
string
- MediaFiles
array
- items MediaFileXml
- TrackingEvents
array
- items TrackingXml
- Duration
MediaFileXml
- MediaFileXml
string
- bitrate
integer
- delivery
string
- type
string
- bitrate
Organization
- Organization
object
: A station that a user has an affiliation with- call required
string
: Station call letters - city required
string
: A short description of the station's main market city - displayName required
string
: A short displayable text field for the end user, strictly text; ignored on PUT - donationUrl
string
: Station donation page URL - id required
string
: Some unique identifier for the organization for the user - logo
string
: Station logo image url - notif_org
array
: The topic in Firebase Cloud Messaging to which the device should subscribe if it supports notifications and the user wants notifications about their localized station.- items
string
- items
- smallLogo
string
: Station logo image url
- call required
OrganizationCategoryAudioListDocument
- OrganizationCategoryAudioListDocument: An array of a certain category of audio recommendations from a provider
- attributes required
object
- errors required
array
: A list of encountered errors, ignored on POST, PUT- items
null
- items
- href required
string
: A URL representation of the resource; should generally be ignored by clients unless noted otherwise - items required
array
- items
null
- items
- links required
object
- version required
string
: The version of the Collection.Doc+JSON spec being used - attributes CategoryData
- items
array
: An array of Audio Items (recommendations)- items AudioItemDocument
- links CategoryLinks
- attributes required
OrganizationOverviewData
- OrganizationOverviewData
object
- brand required Brand
- home
boolean
: Flag indicating if the current view is in the user's home network - orgId required
integer
: The unique identifier for the organization - type required
string
(values: organization): The type of list returned; will always beorganization
OrganizationOverviewDocument
- OrganizationOverviewDocument: a variety of details about an organization including various lists of recent audio items
- attributes required
object
- errors required
array
: A list of encountered errors, ignored on POST, PUT- items
null
- items
- href required
string
: A URL representation of the resource; should generally be ignored by clients unless noted otherwise - items required
array
- items
null
- items
- links required
object
- version required
string
: The version of the Collection.Doc+JSON spec being used - attributes OrganizationOverviewData
- items
array
: A list of separate documents which each include their own list of audio - links OrganizationOverviewLinks
- attributes required
OrganizationOverviewLinks
- OrganizationOverviewLinks
object
- image
array
: One or more links to an image that can be as for branding (logo and small logo)- items ImageLink
- related
array
: One or more links to related web pages for the organization (their twitter feed or facebook page for example)- items OtherLink
- web
array
: One or more links to main page for the organization (their homepage for example)- items OtherLink
- image
OtherLink
- OtherLink: An individual link from a list of links
- href required
string
: The link to be followed - content-type required
string
(values: application/json, application/xml, text/html): The MIME type of the response of this link; note that the enumerated list of possible values is not exhaustive and other MIME types could occur. The list should be treated as examples, rather than absolutes.
- href required
RatingData
- RatingData
object
- affiliations
array
: An array of IDs & other data about collections or podcasts the user has ratings for; produced by the server and should be sent back as received; used for tracking program and podcast suggestions- items
null
- items
- channel required
string
: The channel this media item was pulled from - cohort required
string
: The primary cohort of the current logged-in user - duration required
integer
: Number of seconds this audio piece is expected to last - elapsed required
integer
: Number of seconds since the start of playback for this media item, as an integer - mediaId required
string
: The media id as given by the media object - origin required
string
: How the recommendation was generated - rating required
string
: String representing the rating - timestamp required
string
: ISO-8601 formatted date/time; typically replaced by the client with the actual rating time
- affiliations
RecommendationOrganization
- RecommendationOrganization
object
: Data about the organization with which this media is associated- donateUrl
string
: The URL of the organization's donate page - homepageUrl
string
: The URL of the organization's homepage - logoUrl
string
: A URL for an image of the organization's logo - name required
string
: The name of the organization
- donateUrl
SearchItemDocument
- SearchItemDocument
object
: A search result, which is either an AggregationAudioItemListDocument or an AudioItemDocument- ifTypeAggregation AggregationAudioItemListDocument
- ifTypeAudio AudioItemDocument
- type required
string
(values: audio, aggregation): The type of search result, which is either an AggregationAudioItemListDocument or an AudioItemDocument
SearchListDocument
- SearchListDocument: An array of aggregation or audio recommendations
- attributes required
object
- errors required
array
: A list of encountered errors, ignored on POST, PUT- items
null
- items
- href required
string
: A URL representation of the resource; should generally be ignored by clients unless noted otherwise - items required
array
- items
null
- items
- links required
object
- version required
string
: The version of the Collection.Doc+JSON spec being used - attributes SearchMetaData
- items
array
: A list of aggregation or audio items (recommendations)- items SearchItemDocument
- links
object
: Not used
- attributes required
SearchMetaData
- SearchMetaData
object
- query required
string
: The search terms used in the original request
- query required
SimpleError
- SimpleError
object
: A simple representation of an error result from an API call, rarely used; in most cases we still return a Collection.doc+JSON document for errors- message required
string
: A message describing the error that occurred - type required
string
: A short string representing the type of error that occurred
- message required
StaticResourceXml
- StaticResourceXml
string
- creativeType
string
- creativeType
StationBrandData
- StationBrandData
object
: An associative array of brand-related metadata for this station- band
string
(values: FM, AM): The subsection of the radio spectrum -- 'AM' or 'FM' -- where this station can be heard - call
string
: The three-to-four-letter identifying code for this station. Please use this with caution; most stations prefer to be identified by theirname
in client applications instead ofcall
. - frequency
string
: Where on the radio dial the station can be heard. If theband
is AM, the frequency will be between 540 and 1600. If theband
is FM, the frequency will be between 87.8 and 108.0. - marketCity required
string
: The city that the station is most closely associated with. This may or may not be the city the station is licensed in and it may or may not be the city that the station or the station's antenna is located in. - marketState required
string
: The state that the station is most closely associated with. This may or may not be the state the station is licensed in and it may or may not be the state that the station or the station's antenna is located in. - name required
string
: The display name for the station. In most cases, this will be the same ascall
letters combined with band. When returning networks, it will return the network name (e.g. Minnesota Public Radio). - tagline required
string
: A short text-logo for the station
- band
StationBrandLink
- StationBrandLink: A link to a web page, logo, or audio file related to the branding of the station
- href required
string
: The link to be followed - content-type required
string
: The MIME type of the response of this link - rel required
string
(values: homepage, logo, small-logo, hello-id-audio, station-message-audio, twitter, facebook): A short string identifier describing the way the way the link relates to the document
- href required
StationData
- StationData
object
- brand required StationBrandData
- eligibility required StationEligibilityData
- guid required
string
: The system's internal unique identifier for a station, not typically used by other APIs or consumers - network required StationNetworkData
- newscast StationNewscastData
- orgId required
string
: The system's unique ID for this station, used across NPR One Microservices and NPR's other APIs
StationDocument
- StationDocument
- attributes required
object
- errors required
array
: A list of encountered errors, ignored on POST, PUT- items
null
- items
- href required
string
: A URL representation of the resource; should generally be ignored by clients unless noted otherwise - items required
array
- items
null
- items
- links required
object
- version required
string
: The version of the Collection.Doc+JSON spec being used - attributes StationData
- items
array
: Not used- items
null
- items
- links StationLinks
- attributes required
StationDonationLink
- StationDonationLink: A link to a pledge page for the station
- href required
string
: The link to be followed - guid
string
: The system's internal unique identifier for a link, not typically used by consumers - title required
string
: The link text, provided by the station, for the URL - typeName required
string
: The semantic name corresponding to thetypeId
- typeId required
string
(values: 4, 27, 28): An identifier for the type of link; '4' denotes a generic pledge page, while '27' is an NPR One-specific pledge page
- href required
StationEligibilityData
- StationEligibilityData
object
: An associative array of eligibility-related metadata for this station- format required
string
: The format of the programming on this station - musicOnly required
boolean
: Whether or not this station only plays music - nprOne required
boolean
: Whether or not this station is considered an NPR One station - status required
string
(values: 1, 9, 10, 12, 15): The status of the station within NPR's system, not typically used by consumers
- format required
StationLink
- StationLink: A link related to the station
- href required
string
: The link to be followed - guid
string
: The system's internal unique identifier for a link, not typically used by consumers - title required
string
: The link text, provided by the station, for the URL - typeName required
string
: The semantic name corresponding to thetypeId
- href required
StationLinks
- StationLinks
object
- brand required
array
: One or more links to a web page for the station- items StationBrandLink
- donation
array
: One or more links to audio files related to this station- items StationDonationLink
- podcasts
array
: One or more links to podcasts related to this station- items StationPodcastsLink
- related
array
: One or more links to miscellaneous related content for the station; these typically are not present, and clients should generally not need to use any of these- items StationRelatedLink
- streams
array
: One or more links to audio streams related to the station- items StationStreamsLink
- brand required
StationListDocument
- StationListDocument: A collection of stations close to you or filtered by search criteria
- attributes required
object
- errors required
array
: A list of encountered errors, ignored on POST, PUT- items
null
- items
- href required
string
: A URL representation of the resource; should generally be ignored by clients unless noted otherwise - items required
array
- items
null
- items
- links required
object
- version required
string
: The version of the Collection.Doc+JSON spec being used - attributes StationSearchMetaData
- items
array
: A list of stations- items StationDocument
- links
object
: Not used
- attributes required
StationNetworkData
- StationNetworkData
object
: Metadata about the network, if this station is part of a network- currentOrgId required
string
: The current station being viewed. Client applications should generally ignore this field. - tier1 StationNetworkTierOneData
- usesInheritance required
boolean
: Whether or not the current station inherits from a parent organization, also referred to as a network
- currentOrgId required
StationNetworkTierOneData
- StationNetworkTierOneData
object
: Metadata about the top-level organization in the network, if this station is part of a network- id required
string
: The unique identifier of the top-level organization in the network - name required
string
: The display name for the top-level organization in the network - status
string
(values: 1, 9, 10, 12, 15): The status of the top-level organization within NPR's system, not typically used by consumers - tier2
array
: One or more stations that are hierarchical children of this organization - usesInheritance required
boolean
: Whether or not this station inherits from a parent organization, also referred to as a network
- id required
StationNetworkTierThreeData
- StationNetworkTierThreeData
object
: Metadata about a tier 3 organization in the network, if this station is part of a network- id required
string
: The unique identifier of a tier 3 organization in the network - name required
string
: The display name for a tier 3 organization in the network - usesInheritance required
boolean
: Whether or not this station inherits from a parent organization, also referred to as a network
- id required
StationNetworkTierTwoData
- StationNetworkTierTwoData
object
: Metadata about a tier 2 organization in the network, if this station is part of a network- id required
string
: The unique identifier of a tier 2 organization in the network - name required
string
: The display name for a tier 2 organization in the network - tier3
array
: One or more stations that are hierarchical children of this organization - usesInheritance required
boolean
: Whether or not this station inherits from a parent organization, also referred to as a network
- id required
StationNewscastData
- StationNewscastData
object
: Metadata about the newscast for this station; newscasts are handled internally by other microservices such as the NPR One Listening Service, so this data should typically not be used by consumers- id required
string
: The ID of the newscast that should be played for this station; this is handled internally by other microservices such as the NPR One Listening Service, so this field should typically not be used by consumers - recency required
integer
: How often the newscast should be played, in minutes; a value ofnull
implies no information is available, and sensible defaults should be used
- id required
StationPodcastsLink
- StationPodcastsLink: A link to an audio podcast or podcast feed related to the station
- href required
string
: The link to be followed - guid
string
: The system's internal unique identifier for a link, not typically used by consumers - title required
string
: The link text, provided by the station, for the URL - typeName required
string
: The semantic name corresponding to thetypeId
- typeId required
string
(values: 9): An identifier for the type of link
- href required
StationRelatedLink
- StationRelatedLink: A link to miscellaneous related content for the station; these typically are not present, and clients should generally not need to use these
- href required
string
: The link to be followed - guid
string
: The system's internal unique identifier for a link, not typically used by consumers - title required
string
: The link text, provided by the station, for the URL - typeName required
string
: The semantic name corresponding to thetypeId
- typeId required
string
: An identifier for the type of link
- href required
StationSearchMetaData
- StationSearchMetaData
object
- city
string
: The city searched for in the original request - lat
number
: The latitude parameter used in the original request - lon
number
: The longitude parameter in the original request - query
string
: The search terms used in the original request - state
string
: The state searched for in the original request
- city
StationStreamsLink
- StationStreamsLink: A link to an audio stream related to the station
- href required
string
: The link to be followed - guid
string
: The system's internal unique identifier for a link, not typically used by consumers - title required
string
: The link text, provided by the station, for the URL - typeName required
string
: The semantic name corresponding to thetypeId
- isPrimaryStream
boolean
: Whether or not this stream is considered the station's primary stream - typeId required
string
(values: 10, 11, 12, 13): An identifier for the type of stream
- href required
TrackingXml
- TrackingXml
string
- event
string
(values: start, firstQuartile, midpoint, thirdQuartile, complete, creativeView)
- event
UserAdData
- UserAdData
object
: All information relevant to a user who has requested sponsorship or submitted tracking information- ipAddress
string
: The TCP/IP address of the client making the request. The server will attempt to grab this from the headers, so it probably does not need to be passed in the body unless you get back an error message stating that we were unable to determine an IP address from the request. - listenerId
string
: A client-designated unique identifier for the logged-in user, only used if neither an NPR.org public user ID nor anX-Advertising-ID
header are available. - userAgent
string
: An identifying string for the browser making the request. The server will attempt to grab this from the headers, so it probably does not need to be passed in the body unless you get back an error message stating that we were unable to determine a User-Agent from the request.
- ipAddress
UserAdDocument
- UserAdDocument: All information relevant to a user who has requested sponsorship or submitted tracking information
- attributes required
object
- errors required
array
: A list of encountered errors, ignored on POST, PUT- items
null
- items
- href required
string
: A URL representation of the resource; should generally be ignored by clients unless noted otherwise - items required
array
- items
null
- items
- links required
object
- version required
string
: The version of the Collection.Doc+JSON spec being used - attributes UserAdData
- items
array
: All the information needed for the Sponsorship Service to send back tracking information to our external sponsorship provider- items AdTrackingDocument
- attributes required
UserData
- UserData
object
: Object; see description of a user object below- affiliations
array
: Program(s) that the user has positively interacted with- items Affiliation
- cohort required Cohort
- email
string
: The user's email address - firstName
string
: The user's first name - id required
string
: Some unique identifier for the user - lastName
string
: The user's last name - organizations required
array
: User's chosen NPR Member Station(s)- items Organization
- affiliations
UserDocument
- UserDocument
- attributes required
object
- errors required
array
: A list of encountered errors, ignored on POST, PUT- items
null
- items
- href required
string
: A URL representation of the resource; should generally be ignored by clients unless noted otherwise - items required
array
- items
null
- items
- links required
object
- version required
string
: The version of the Collection.Doc+JSON spec being used - attributes UserData
- items
array
: Not used, ignored on a PUT- items
null
- items
- links
object
: A list of links, not used by the Identity Service; ignored on a PUT
- attributes required