API Use Case
The most popular reason for the Parse.ly API is powering a client-side widget to boost recirculation. Let’s look at a finished example of this API use case.
We could place the following widget on the article describing our Google Search Console integration.
How to create your own recommendations widget
Select an API Endpoint
Review our endpoints to find something that works with your strategy. In our example, we’ll use the /related endpoint. Our API call will look like this:
https://api.parsely.com/v2/related?apikey=docs.parse.ly&url=https://docs.parse.ly/gsc-integration-steps/&sort=score&limit=3&page=1&respect_empty_results=1Be sure to edit all applicable fields:
apikey= your Site ID- Some endpoints will require an API Secret.
- All endpoints require the purchase of API Access. If you’re interested in this, you can contact your relationship manager. If you’ve purchased API access but don’t see your secret on the API Settings Page, contact support@parsely.com. If you cannot see the API Settings Page, and you ought to, contact your team’s dashboard administrators on your account settings page.
- Review the desired endpoint documentation for additional details.
Design your widget (or copy ours)
If you wish to copy our example, you can modify the CSS to suit your style guide.
<div class="parsely-recommendation-widget display-thumbnail list-horizontal" id="parsely-widget">
<script>(function() {
let parselyDiv = document.getElementById('parsely-widget');
let httpRequest = new XMLHttpRequest();
let apiResults;
let cssString = '.parsely-recommended-widget{font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif,"Apple Color Emoji","Segoe UI Emoji","Segoe UI Symbol";width:100%}.parsely-recommended-widget .poweredBy{display:inline-block;justify-self:start;margin-top:.5em;color:#bfbfbf;font-weight:300;text-decoration:none;font-size:.75em}.parsely-recommended-widget .articles{display:grid;grid-row-gap:2em;grid-column-gap:1.25em;grid-template-columns:repeat(3,1fr);align-items:flex-start;padding-top:.45em;width:100%;max-width:1400px;margin-left:auto;margin-right:auto}.parsely-recommended-widget .recommendItem{border:1px solid #e0e0e0;display:flex;flex-direction:column;justify-content:start;align-items:flex-start;height:100%;border-radius:5px;background:#fff;box-shadow:0 2px 15px 0 rgba(23,23,27,.1);text-decoration:none;transition:all .16s ease-out;color:currentColor;max-width:320px}.parsely-recommended-widget .thumbnailDiv{width:100%;height:160px;display:flex;overflow:hidden;margin-bottom:0.5em}.parsely-recommended-widget .thumbnailDiv img{margin:0;padding:0;width:100%;height:auto;display:block;align-self:center}.parsely-recommended-widget .section,.parsely-recommended-widget .date,.parsely-recommended-widget .title,.parsely-recommended-widget .author{padding:0 0.5rem 0.25rem 0.5rem;margin:0}.parsely-recommended-widget .section{text-transform:uppercase;letter-spacing:.1em;font-size:.8em;font-weight:500;padding-top:.5em}.parsely-recommended-widget .date{font-size:.85em;font-weight:400;color:#a9aaab}.parsely-recommended-widget .title{font-size:1.25em;line-height:1.45;margin-bottom:0}.parsely-recommended-widget .author{font-size:.775em;font-weight:400;padding-top:.5em}@media(max-width:1200px){.parsely-recommended-widget .articles{grid-template-columns:repeat(2,1fr)}}@media(max-width:600px){.parsely-recommended-widget .articles{grid-template-columns:1fr}}';
let cssStyle = document.createElement('style');
let cssStyleContent = document.createTextNode(cssString);
cssStyle.appendChild(cssStyleContent);
document.body.prepend(cssStyle);
let widgetContainer = document.createElement('div');
widgetContainer.classList.add('parsely-recommended-widget');
/* --- Powered by Parse.ly --- */
let poweredBy = document.createElement('a');
poweredBy.classList.add('poweredBy');
poweredBy.appendChild(document.createTextNode('Powered by Parse.ly'));
poweredBy.setAttribute("href", 'https://www.parse.ly');
widgetContainer.appendChild(poweredBy);
/* --- */
let articles = document.createElement('div');
articles.classList.add('articles');
widgetContainer.appendChild(articles);
let months = [
"January","February","March","April","May","June",
"July","August","September","October","November","December",
];
httpRequest.open("GET", "https://api.parsely.com/v2/related?apikey=docs.parse.ly&url=https://docs.parse.ly/gsc-integration-steps/&sort=score&limit=3&page=1&respect_empty_results=1", true);
httpRequest.onload = function (e) {
if (httpRequest.readyState === 4) {
if (httpRequest.status === 200) {
apiResults = JSON.parse(httpRequest.responseText)['data'];
apiResults.forEach((result) => {
let recommendItem = document.createElement('a');
recommendItem.classList.add('recommendItem');
recommendItem.setAttribute("href", result['url']);
/* --- Image --- */
let hasImage = result['image_url'] && result['image_url'] != undefined;
if (hasImage) {
let imgContainer = document.createElement('div');
imgContainer.classList.add('thumbnailDiv');
recommendItem.appendChild(imgContainer);
let imgTag = document.createElement('img');
imgTag.setAttribute('src', result['image_url']);
imgContainer.appendChild(imgTag);
} else {
recommendItem.classList.add('noImage');
}
/* --- */
/* --- Section --- */
let hasSection = result['section'] && result['section'] != undefined;
if (hasSection) {
let section = document.createElement('div');
section.classList.add('section');
let s = document.createTextNode(result['section']);
section.appendChild(s);
recommendItem.appendChild(section);
}
/* --- */
/* --- Date --- */
let d = new Date(result['pub_date'])
let hasDate = d && result['pub_date'] != undefined;
if (hasDate) {
let dateElement = document.createElement('h4');
dateElement.classList.add('date');
let day = d.getDate();
let monthIndex = d.getMonth();
let monthName = months[monthIndex];
d = monthName + " " + day;
let date = document.createTextNode(d);
dateElement.appendChild(date);
recommendItem.appendChild(dateElement)
}
/* --- */
/* --- Title --- */
let title = document.createElement('h3');
title.classList.add('title');
let t = document.createTextNode(result['title']);
title.appendChild(t);
recommendItem.appendChild(title);
/* --- */
/* --- Author --- */
let hasAuthor = result['author'] && result['author'] != undefined;
if (hasAuthor) {
let author = document.createElement('h4');
author.classList.add('author');
let a = document.createTextNode("by " + result['author']);
author.appendChild(a);
recommendItem.appendChild(author);
}
/* --- */
articles.appendChild(recommendItem);
});
} else {
console.error(httpRequest.statusText);
}
}
};
httpRequest.onerror = function (e) {
console.error(httpRequest.statusText);
};
httpRequest.send(null);
parselyDiv.appendChild(widgetContainer);
})();</script>
</div>
Not to be confused with the Content API
- WPVIP customers also have access to Content Helper. Content Helper has an optional add-on to use generative AI to power pre-publishing tools right in the WordPress CMS.
- The Data Pipeline (DPL) is an unrelated product that provides our raw data to your data science team to store and use as desired. With DPL, a skilled team could create their own dashboard; the API is not suitable for that purpose.
Last updated: November 07, 2024