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=1

Be 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 Parse.ly Support. 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 () {
  '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>

<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';

// ── 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