Title: API Use Case
Author: joshua
Published: November 7, 2024
Last modified: July 20, 2026

---

 1. [The Parse.ly API](https://docs.parse.ly/api/)
 2. API Use Case

#  API Use Case

The most popular reason for the Parse.ly API is powering a client-side widget to
boost [recirculation](https://docs.parse.ly/recirculation-rate/). 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](https://docs.parse.ly/gsc-integration-steps).

## How to create your own recommendations widget

### Select an API Endpoint

Review [our endpoints](https://docs.parse.ly/api-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:

    ```lang-php
    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
    ```

Be sure to edit all applicable fields:

 * `apikey` = your [Site ID](https://docs.parse.ly/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](https://docs.parse.ly/api-settings/),
   contact [Parse.ly Support](https://support.parse.ly/hc/en-us). If you cannot 
   see the API Settings Page, and you ought to, contact your team’s dashboard administrators
   on your [account settings page](https://docs.parse.ly/api-settings/).
 * Review the desired [endpoint documentation](https://docs.parse.ly/api-endpoints/)
   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.

    ```lang-html
            <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>
    ```

Last updated: July 20, 2026