Welcome to the PMP! These user guides are intended to help you:
- Register for a PMP account
- Manage your API credentials
- Find and install existing PMP integrations or plugins
- Setup your content management system
- Understand the high-level data structure of the PMP
If you’re a developer looking to use/build an SDK, you probably want to head over to the developer docs.
To access the PMP, your station must have a PMP account with credentials. These credentials allow the PMP API to approve requests to access PMP content, identify who is pulling content, and what content is being pulled by each account. There are a few steps required to complete your PMP API account and credential set up: requesting an account, setting a password, setting proper permissions to the account, and copying your account details to use in your CMS or application.
Note: Typically, one account is set up per organization and the login and password are shared securely amongst people in that organization who will be using the PMP. Under that account, individual credentials can be set up for each tool/product/site, so if you’re using the PMP for multiple applications, you will need to set up separate credentials (but not accounts) for each. In some cases, an organization may wish to set up a separate account for an application that will be uniquely branded; in these cases please contact firstname.lastname@example.org.
Note for developers: Though you may have the same username for each, PMP sandbox and production accounts are otherwise independent.
If you already have an account, you can log in to manage your user.
Request An Account
Complete the request form for a new account.
Host: Select api.pmp.io if you intend to use an existing PMP plugin or Core Publisher. Choose api-sandbox.pmp.io if you are a developer and want an account to perform testing in a sandbox environment.
Contact email: We recommend that stations use a generic email address rather than a personal email account. If there is a change in personnel, you cannot change the email account tied to the API user account.
Name of organization: Enter your Station call letters.
What CMS do you use? Select the CMS you currently use, or select ‘Other’ and provide a description in the field below.
You will receive an email reply to your request within 48 hours.
Reset Your Password
Once you receive the email with your PMP credentials, you will need to set a password for your account.
Complete the reset password form.
Select the Host “api.pmp.io” or “api-sandbox.pmp.io” as appropriate from the dropdown menu.
Enter the username used to sign up for your PMP account.
Click “Email reset instructions.”
An email from email@example.com will be sent to the address associated with your username with further instructions. Click the link in the email to visit the page where you can confirm your username and enter a new password. Once you confirm your new password, a screen alert will let you know that your password has been changed, and you will be redirected to the login page.
Create Your Credentials
Now that you have reset your password and are able to login, you can create unique credentials for your PMP account.
Go to the “Login” page. * Sign in with your username and password.
Click the green “New Client” button on the credentials page.
Select the “write” option from the “Scope” column (“write” scope will allow you to push content into the PMP).
Type an appropriate identifier for your CMS (Core Publisher, WordPress, Bento, etc.) into the “your-label-here” field, found under the “Label” column.
Click “Save” in the “Actions” column.
The “Client ID” and the “Client Secret” columns should now be populated with unique alphanumeric strings. Record the values for your Client ID and Client Secret in a secure place as you will need to include them in your application or CMS plugin to complete the set up process.
Save Your Credentials
Record the values for your Client ID and Client Secret in a secure place as you will need to include them in your application or CMS plugin to complete the set up process.
Record Your PMP GUID
The final piece of information you will need to complete your PMP setup is your GUID, or Globally Unique Identifier. You can find this on your PMP account page.
Return to your PMP account dashboard.
Click on your username in the upper right corner of the screen, and select “Manage User”.
On the left-hand side of your screen, you will see a field identified as “GUID”. The alphanumeric string is the unique GUID for your account. Record this value in a secure place for future use in your application or CMS plugin.
Congratulations, you have successfully set up credentials for accessing the PMP API! Next, you’ll need to use this information to set up the application you will use to make requests to the PMP. Instructions for that process should be available from the application or plugin provider; NPR member stations using the Core Publisher plugin can find that information on NPR’s Digital Services website.
NOTE: For additional support or any questions about your PMP user account please contact the PMP directly at firstname.lastname@example.org.
Plugins for several popular platforms are available or are in development. If you know of any additional integrations, or would like to build one yourself, please contact us at email@example.com.
|Core Publisher||NPR DS||Y||Both||Soon||Y||Y||N||Y|
The Bento plugin allows you to push content into the PMP manually or automatically. It also allows you to pull full story content manually or automatically as blog posts, or to pull individual story headlines/teasers/photos from the PMP via Bento’s Explorer Custom Promo smart snippet.
The CP plugin allows you to set up automatic pulls of stories for your program pages, and to manually pull individual stories.
This plugin allows your Drupal site to pull and push content to/from the PMP.
This PMP importer allows you to import individual stories from PRX (via the PRX story ID) or an RSS feed of stories (via an RSS URL).
A guide to some terminology you may encounter while using the PMP.
This is a guide primarily geared toward users of the PMP rather than developers. More technical information on many of these terms is available in the developer documentation.
Note that the PMP is extremely flexible, which is one of its strengths, but that also means that not every content producer will structure their content in the same way. Some producers may use tags for their content, for example, while others may not.
Every piece of data in the PMP is referred to as a Document. These are generally broken down into the smallest possible components. A piece of audio is a Document. An image is a Document. The HTML providing the context for those images and audio is a Document.
Documents contain text attributes and links to other resources on the internet. Documents do not store any binary media assets – photos, audio and video files are all stored elsewhere. The PMP Documents simply point to the URLs where those assets are stored.
Documents are identified via a GUID (a globally unique identifier). The GUID for PRI’s The World programs is
4d3a942d-91c0-46a5-86df-9338f88c8487. The GUID for the NPR story “Yoink! Dad Nabs Foul Ball While Holding Baby At Cubs Game” is
You’ll often need to find the GUID for a Document in order to use it in your application. The PMP Support Searcher provides an easy way to find and copy a GUID – just hover over the numbers/letters in the lower-right corner of any search result.
Documents come in various flavors or “Profile Types.” This allows consumers and producers to differentiate between textual, media, and organizational content. In other words, the PMP metadata around an audio clip will look quite different than the metadata around journalistic series. Profiles give consumers the flexibility to search for and segment PMP content in interesting ways.
Here is a list of some common Document Profile types, what they contain, and how they relate to each other:
A Story Document glues together all of the various media/text elements into a self-contained whole. The vast majority of the time, Stories are what people will be concerned with when pushing and pulling from the PMP. Stories can include: text, teasers, Audio, Images, Video, and other organizing information (the program the Story came from, who created the Story, etc.)
An Image Document represents a single picture, including multiple crops of that image. All images in the PMP require at minimum a human-readable title, a source URL, and at least one crop of the image. Captions and credits are also recommended.
Audio Documents are used to represent a certain chunk of audio. They can include multiple file-types/quality of files (mp3, ogg, m3u, etc), and optionally an embeddable player for the audio stream. A human-readable title for the Audio is required, and captions and credits are recommended.
Unlike other media, Video Documents often don’t include a link to a binary source file (like a jpg or mp3 file). Instead, they include an embeddable-player that a PMP consumer can use to play that video from their web or mobile app. Multiple video qualities/resolutions are recommended to support mobile platforms. A human-readable title is required, and captions and credits are recommended.
We use the term Collection to refer to the relationship between Documents in the PMP. And (you’ll want to remember this one) every Document in the PMP is a potential Collection of other Documents. A Story like “How do you explain the leap second to a 6-year-old?” is a Collection of Audio and Images. A Series like State of the Re:Union Fall 2010 Season is a Collection of Stories produced during that 2010 season. And a Topic like Money is a Collection of Stories related to finances and banking.
As opposed to a text search, searching by one of these PMP Collections will return only Documents specifically assigned to the GUID of that Collection.
The five primary Collections used in the PMP are:
If the structure of content in the PMP is depicted as a pyramid, Properties are on top. They are often the equivalent to a broadcast program (examples: The Moth, PRI’s The World), but in some cases they are more akin to a brand (example: Marketplace, which includes all incarnations of Marketplace programming such as Marketplace, Marketplace Morning Report, etc.). A search by the GUID of The Moth Property will return all Stories and items associated with that Property. A similar search using the Marketplace Property GUID will likewise return all Stories and items associated with that Property, which includes all programs under the Marketplace umbrella.
A Collection of related Stories. As opposed to Properties, Series are more loosely defined. In some cases, they may correspond to a broadcast program, but also could be used to collect Episodes of a program or a selection of Stories from multiple Episodes of a program. Examples: Marketplace Morning Report, State of the Re:Union Fall 2013 Series, American Routes, or MPR News' “On Campus” series. The occasional Morning Edition on-air series “Crime in the City” could also have been collected in the PMP as a Series.
An ordered list of stories that are usually the equivalent to a broadcast episode. Example: Marketplace Morning Report for June 8, 2015.
The PMP currently has twelve defined Topics for classifying PMP Stories and Episodes by subject matter. Examples: money, technology. Stories and Episodes can be assigned to multiple topics. Topics allow for retrieval of content by similar subject from multiple producers. Here’s the complete list of topics.
The person largely responsible for a Story – equivalent to a byline. Allows for the return of all Stories credited to an individual. Stories can have multiple Contributors. Example: all the Stories in the PMP by Kai Ryssdal.
Free-form attributes of a Document in the PMP. They are human readable, and describe the Document itself – not metadata about the Document. Content creators can assign any tags that they’d like for their content. Examples: Stories tagged with “movie” and Stories tagged with “money”. Sadly, there are no Stories currently tagged with his majesty Buck Showalter.
By default, any Document (Story/Image/Audio/etc.) in the PMP is public. But permissions can be optionally assigned to any Document, restricting read access to a list of Groups.
Remember that any data in the PMP is a document, so permissions can be assigned to a Property, an individual Story, or even a photo within a Story or a Story’s Audio. Any User in any of those Groups will be able to see/read the doc.
Example: PRI created a Group for PRI’s The World, and to that Group they added Users which are stations corresponding to their broadcast carriage list. Any content from The World that is published to the PMP is available to those Users and only those Users.
And here’s a diagram illustrating how permissions can be set in the PMP. Each of the different organizations can be set to have access to different documents:
Okay, so now you know that everything in the PMP is a Document. But how do these Documents relate to each other?
Here are a couple of illustrations of how broadcast programs could be set up in the PMP:
If you have questions or suggestions regarding any of this, please let us know!
Using the PMP Searcher
The support site searcher (https://support.pmp.io/?advanced=1&profile=story&has=image) was created primarily as a tool for PMP development, but it is a handy tool that can be used by anyone to quickly find content in the PMP.
Why use the Support Site Searcher?
Though many of the CMS plugins have PMP search built in, it is often easier to use the support searcher to find what you’re looking for. The support searcher is:
Fast. It’s the quickest way to search for content in the PMP.
Easy. Once you get the hang of it, it’s easy to find the asset you’re looking for and pull it into the CMS you’re using.
Powerful. With the PMP searcher you can specify exactly what you’re looking for, making use of all of the metadata available to find what you need.
Important! The searcher may have different content permissions than your PMP account, so assets you may find in the searcher may not be available to you. Example: if your account does not have rights to content to PRI’s The World, you will not be able to add content from The World to your site even though you can find it in the support searcher.
By default, the searcher returns stories that have an image. We’ll stick with that to perform our first searches. Let’s do a text search. First, enter “star wars” (without quotes) in the search box and hit search.
It returns over 2,500 stories, and the first one returned features Star Trek’s George Takei. Probably not what we’re looking for. Without quotes, the query will return any instance of “star” or “wars” within story text, headlines, teasers and bylines.
If we put quotes around “star wars” we may be getting a little closer. The 109 stories returned do have a mention of “Star Wars” in them. But they’re not really about Star Wars:
If we specify where in the stories we want the phrase “star wars” to appear, we may get what we’re after. A search for
title:"Star Wars" OR teaser:"Star Wars" returns results with photos of Stormtroopers in them. We’re in business:
And for fun, one more search before leaving this universe:
teaser:"Star Trek" OR teaser:"Star Wars".
So for text searches: * Use quotes for exact phrases
The searcher will look for your query in story text, titles, teasers and bylines
Tell the PMP where to search (ex: title) to provide better results.
Use AND or OR for searching for multiple phrases or to search multiple fields.
Once you find the story (or asset) you’re looking for, you need to retrieve its GUID to be able to pull it into your CMS and use it in your site or app. A GUID is a unique identifier that every document in the PMP has, no matter what it is (image, story, audio, etc.) Here’s the GUID of the top story above: 2d36795c-8cec-4545-84f0-bd20404b1f1b.
Getting the GUID is pretty easy: click on the box in the lower right corner of the story’s search result and hit CTRL+C to copy:
You can then take that GUID and put it in your CMS. Here’s how it’s done in Core Publisher:
Tweaking Search Results
If you look at the top right of the search results, you’ll see that the default is to return the most recent results:
By clicking on one of the other options (Title and Most Relevant), you can reorder the search results in ways that may make more sense. While Most Recent is probably best when searching for a recent news story, ordering results by Title may be better when searching for collections like Properties and Series. Ordering by Most Relevant may be useful when a search yields many results.
Using The Checkboxes
To get the most out of the support searcher it helps to have a basic understanding of the PMP terms that can be used to refine your search. The PMP terminology guide explains it all, but below is a quick summary of the ones you need to know.
Note that you need to click the ‘more’ link in the searcher’s Type box to see all of the options listed below. Also know that because of the flexibility built into the PMP, not all content is organized the same. Some content providers make use of Series, for example, while others do not. See a couple of hypothetical ways content in the PMP can be organized here.
Here are definitions of some of the less obvious checkboxes/form fields:
Property: If the structure of content in the PMP were depicted as a pyramid, Properties would be on top. They are often equivalent to a broadcast program (examples: The Moth, PRI’s The World), but in some cases they are more akin to a brand (example: Marketplace, which includes all incarnations of Marketplace programming such as Marketplace, Marketplace Morning Report, etc.). This search by the GUID of The Moth Property will return all Stories and items associated with that Property. A similar search using the Marketplace Property GUID will likewise return all Stories and items associated with that Property, including all programs under the Marketplace umbrella.
Series: A Collection of related Stories. As opposed to Properties, Series are more loosely defined. In some cases, they may correspond to a broadcast program, but also could be used to collect Episodes of a program or a selection of Stories from multiple Episodes of a program. Examples: Marketplace Morning Report, State of the Re:Union Fall 2013, American Routes, or MPR News' “On Campus” series.
Episode: An ordered list of stories that are usually the equivalent to a broadcast episode. Example: Marketplace Morning Report for June 8, 2015.
Topics: The PMP currently has twelve defined Topics for classifying PMP Stories and Episodes by subject matter. Examples: sports, technology. Stories and Episodes can be assigned to multiple topics. Topics allow you to find content of similar subject matter from multiple producers. Here’s the complete list of topics.
Tags: Like Topics, but free-form. Producers can add whatever tags they want to an asset. Like many things in the PMP, not everyone uses tags in a consistent way. There are many more stories in the money topic than there are stories tagged with “money.”
Contributors: The person largely responsible for a Story – equivalent to a byline. Allows for the return of all Stories credited to an individual. Stories can have multiple Contributors. Example: all Stories in the PMP by Kai Ryssdal.
Great, so how do I use this? How do I know if something is organized in the PMP as a Series or as a Property?
Though Series, Properties and Contributors and other documents can be used to help searching, you can also use the PMP to find these things themselves. * Properties in the PMP * Series in the PMP * Contributors in the PMP
To do searches like this, make sure that you have only checked one box for the specific criteria you are looking for before you hit the search button.
Here’s what the Contributors search setup looks like, and the top result:
Notice that in the lower right corner where you copy the GUID from, it says “Collect.” This means that the GUID is a collection rather than a single document GUID. I can copy that GUID back into search to retrieve all of Melanie’s stories in the PMP. I can also click on “Collect” and the PMP will automatically run a search for that Collection:
Similarly, if I know the GUID of a particular Property, I can use it to find everything associated with that Property. Here’s a search for The Takeaway Property:
Combining Search Queries
You can combine search queries in various ways; for example, here is a search for stories published from The World in the last two years with audio and with “religion” in the teaser:
Multiple Collection Searches
You can query with multiple collections by putting them all in the collections box. Separating GUIDs with a semicolon is “OR,” and with a comma is “AND.” The PMP also automatically converts Topics into their GUID, so a search for Marketplace stories within the Topic money looks like the following:
Using the techniques detailed above, you too can become a Support Searcher Pro. You’ll find what you’re looking for quickly. It looks like a lot, but after you’ve used it a few times, it will click and become intuitive. If something isn’t clicking or doesn’t make sense, drop us a line at firstname.lastname@example.org and we’ll be happy to help you out!