Title: API Use Case
Author: joshua
Published: November 7, 2024
Last modified: August 6, 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 () {
      'use strict';

      // ── Constants ──────────────────────────────────────────────────────────────
      const WIDGET_ROOT_ID = 'parsely-widget';
      const STYLES_ID      = 'parsely-widget-styles';
      const API_URL        = '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';

      const CSS = `
        .parsely-recommended-widget {
          --parsely-green:      #54c45e;
          --parsely-green-dark: #3da847;
          --parsely-green-pale: #edf8ee;
          --text-primary:       #1a1a1a;
          --text-secondary:     #6b6b6b;
          --text-muted:         #a9aaab;
          --card-border:        #e4e4e4;
          --card-radius:        6px;
          --card-shadow:        0 2px 15px 0 rgba(23, 23, 27, 0.08);
          --card-shadow-hover:  0 8px 28px 0 rgba(23, 23, 27, 0.16);
          --thumb-height:       180px;
          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-flex;
          align-items: center;
          gap: 0.3em;
          margin-bottom: 0.6em;
          color: var(--text-muted);
          font-weight: 400;
          font-size: 0.75em;
          text-decoration: none;
          transition: color 0.16s ease-out;
        }
        .parsely-recommended-widget .poweredBy:hover {
          color: var(--parsely-green-dark);
        }
        .parsely-recommended-widget .articles {
          display: grid;
          grid-template-columns: repeat(3, 1fr);
          gap: 1.25em;
          align-items: stretch;
          padding-top: 0.45em;
          width: 100%;
          max-width: 1400px;
          margin-inline: auto;
        }
        .parsely-recommended-widget .recommendItem {
          border: 1px solid var(--card-border);
          display: flex;
          flex-direction: column;
          align-items: flex-start;
          height: 100%;
          border-radius: var(--card-radius);
          background: #fff;
          box-shadow: var(--card-shadow);
          text-decoration: none;
          color: var(--text-primary);
          max-width: 320px;
          transition: transform 0.16s ease-out, box-shadow 0.16s ease-out;
        }
        .parsely-recommended-widget .recommendItem:hover {
          transform: translateY(-4px);
          box-shadow: var(--card-shadow-hover);
        }
        .parsely-recommended-widget .recommendItem:focus-visible {
          outline: 2px solid var(--parsely-green);
          outline-offset: 2px;
        }
        .parsely-recommended-widget .thumbnailDiv {
          width: 100%;
          height: var(--thumb-height);
          overflow: hidden;
          margin-bottom: 0.5em;
          flex-shrink: 0;
          border-radius: var(--card-radius) var(--card-radius) 0 0;
          background: var(--parsely-green-pale);
        }
        .parsely-recommended-widget .thumbnailDiv img {
          width: 100%;
          height: 100%;
          object-fit: cover;
          display: block;
        }
        .parsely-recommended-widget .thumbnailDiv.noImage {
          background: linear-gradient(150deg, var(--parsely-green-pale) 0%, #f5f9f5 100%);
          display: flex;
          align-items: center;
          justify-content: center;
        }
        .parsely-recommended-widget .thumbnailDiv.noImage::after {
          content: '';
          display: block;
          width: 52px;
          height: 52px;
          opacity: 0.25;
          background: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'%3E%3Cpath fill='%2354c45e' d='M17 8C8 10 5.9 16.17 3.82 21.34L5.71 22l1-2.3A4.49 4.49 0 0 0 8 20C19 20 22 3 22 3c-1 2-8 2-14 6 1-1 2.5-2 5-3z'/%3E%3C/svg%3E")
            center / contain no-repeat;
        }
        .parsely-recommended-widget .section,
        .parsely-recommended-widget .date,
        .parsely-recommended-widget .title,
        .parsely-recommended-widget .author {
          padding: 0 0.6rem 0.3rem;
          margin: 0;
        }
        .parsely-recommended-widget .section {
          text-transform: uppercase;
          letter-spacing: 0.1em;
          font-size: 0.75em;
          font-weight: 600;
          padding-top: 0.6em;
          color: var(--parsely-green-dark);
        }
        .parsely-recommended-widget .date {
          font-size: 0.85em;
          font-weight: 400;
          color: var(--text-muted);
        }
        .parsely-recommended-widget .title {
          font-size: 1.15em;
          line-height: 1.45;
          font-weight: 700;
          color: var(--text-primary);
          margin-bottom: 0;
        }
        .parsely-recommended-widget .recommendItem:hover .title {
          color: var(--parsely-green-dark);
          transition: color 0.16s ease-out;
        }
        .parsely-recommended-widget .author {
          font-size: 0.775em;
          font-weight: 400;
          color: var(--text-secondary);
          padding-top: 0.4em;
          padding-bottom: 0.75em;
          margin-top: auto;
        }
        @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;
          }
        }
      `;

      // ── Helpers ────────────────────────────────────────────────────────────────

      function injectStyles() {
        if (document.getElementById(STYLES_ID)) return;
        const style = document.createElement('style');
        style.id = STYLES_ID;
        style.textContent = CSS;
        document.head.appendChild(style);
      }

      function formatDate(isoString) {
        if (!isoString) return null;
        const date = new Date(isoString);
        if (isNaN(date.getTime())) return null;
        return date.toLocaleDateString('en-US', {
          month: 'long',
          day:   'numeric',
          year:  'numeric',
        });
      }

      function buildCard(result) {
        const card = document.createElement('a');
        card.classList.add('recommendItem');
        card.href   = result.url;
        card.target = '_blank';
        card.rel    = 'noopener noreferrer';

        const imgContainer = document.createElement('div');
        imgContainer.classList.add('thumbnailDiv');

        if (result.image_url) {
          const img = document.createElement('img');
          img.src     = result.image_url;
          img.alt     = result.title || '';
          img.loading = 'lazy';
          imgContainer.appendChild(img);
        } else {
          imgContainer.classList.add('noImage');
        }

        card.appendChild(imgContainer);

        // Section
        if (result.section) {
          const section = document.createElement('div');
          section.classList.add('section');
          section.textContent = result.section;
          card.appendChild(section);
        }

        // Date
        const formattedDate = formatDate(result.pub_date);
        if (formattedDate) {
          const dateEl = document.createElement('time');
          dateEl.classList.add('date');
          dateEl.setAttribute('datetime', result.pub_date);
          dateEl.textContent = formattedDate;
          card.appendChild(dateEl);
        }

        // Title
        const title = document.createElement('h3');
        title.classList.add('title');
        title.textContent = result.title;
        card.appendChild(title);

        // Author
        if (result.author) {
          const author = document.createElement('p');
          author.classList.add('author');
          author.textContent = `by ${result.author}`;
          card.appendChild(author);
        }

        return card;
      }

      // ── Init ───────────────────────────────────────────────────────────────────

      async function init() {
        const widgetRoot = document.getElementById(WIDGET_ROOT_ID);
        if (!widgetRoot) return;

        injectStyles();

        const container = document.createElement('div');
        container.classList.add('parsely-recommended-widget');

        const poweredBy = document.createElement('a');
        poweredBy.classList.add('poweredBy');
        poweredBy.href        = 'https://www.parse.ly';
        poweredBy.target      = '_blank';
        poweredBy.rel         = 'noopener noreferrer';
        poweredBy.textContent = 'Powered by Parse.ly';
        container.appendChild(poweredBy);

        const articlesEl = document.createElement('div');
        articlesEl.classList.add('articles');
        container.appendChild(articlesEl);

        widgetRoot.appendChild(container);

        try {
          const response = await fetch(API_URL);
          if (!response.ok) throw new Error(`HTTP ${response.status}`);
          const { data } = await response.json();
          data.forEach((result) => articlesEl.appendChild(buildCard(result)));
        } catch (err) {
          console.error('[Parse.ly widget] Failed to load recommendations:', err);
        }
      }

      init();
    }());
    </script>
    </div>
    ```

Last updated: August 06, 2026