API, Blog, PHP

Quotes API

Some time back we wrote a minimal Quotes WordPress plugin that'd do nothing other than render a single quote into a WordPress website. While the nature of the plugin was exceedingly simple, the API itself is quite complete, and it provides quote data to our social media and marketing system. We've recently migrated the API over to its new home in preparation for our new platform and, as always, it's available to all our current and former clients for use in any manner that floats their boat.

While the source is one of a few quotes databases that we use, it's one of the more comprehensive. This article describes (in brief) how to access the data.

The Result

Data may be queried by quote ID (for a single quote), or by search term, author, or genre. Regardless of what query is made, the data array returned in each case includes identical fields. The endpoint in all cases is as follows:

https://api.beliefmedia.com/platform/sources/quotes/quotes.json

An API Key is required, and an optional pg and number parameter may be supplied for pagination purposes. If searching results the search type must be provided: search (for text searches), author (by author_slug), or by genre (genre_slug). If no search type is provided, the browse type is assumed.

Returning a Single Quote

A single quote may be returned as follows: quotes.json?apikey=xxxxx&id=gY. The result:

Array

(

[code] => 200

[status] => 200

[message] => OK

[source] => BeliefMedia

[data_version] => 0.2

[data] => Array

(

[id] => gY

[quote] => Age is an issue of mind over matter. If you don't mind, it doesn't matter.

[author] => Mark Twain

[full_quote] => "Age is an issue of mind over matter. If you don't mind, it doesn't matter." - Mark Twain

[info] => Array

(

[quote_characters] => 74

[quote_words] => 15

[author_slug] => mark-twain

[author_count] => 128

[genre_name] => Age

[genre_slug] => age

[genre_count] => 998

)

=> Array

(

[filename] => mark-twain/gY.jpg

[size] => 80.5K

[width] => 885

[height] => 885

)

The image referenced is a branded quote on our server (with its parent directory). The author_slug and genre_slug in the info array are provided for search purposes.

Searching by Text, Author, Genre, or Browsing

In all search cases, the results are returned in an identical manner. Example queries are as follows:

quotes.json?apikey=xxx&type=search&search=money (searching for text "money").
quotes.json?apikey=xxx&type=author&search=mark-twain (searching Mark Twain).
quotes.json?apikey=xxx&type=genre&search=age (Searching "age" genre).
quotes.json?apikey=xxx&pg=15&number=20 (Browsing with pagination).

An example response is as follows:

Array

(

[code] => 200

[status] => 200

[message] => OK

[source] => BeliefMedia

[data_version] => 0.2

[page] => 1

[number] => 30

[pages] => 2532

[total] => 75966

[search] => Array

(

[type] => browse

)

[results] => Array

(

[0] => Array

(

[id] => gY

[quote] => Age is an issue of mind over matter. If you don't mind, it doesn't matter.

[author] => Mark Twain

[full_quote] => "Age is an issue of mind over matter. If you don't mind, it doesn't matter." - Mark Twain

[info] => Array

(

[quote_characters] => 74

[quote_words] => 15

[author_slug] => mark-twain

[author_count] => 128

[genre_name] => Age

[genre_slug] => age

[genre_count] => 998

)

=> Array

(

[filename] => mark-twain/gY.jpg

[size] => 80.5K

[width] => 885

[height] => 885

)

[1] => Array

(

[id] => jR

[quote] => Anyone who stops learning is old, whether at twenty or eighty. Anyone who keeps learning stays young. The greatest thing in life is to keep your mind young.

[author] => Henry Ford

[full_quote] => "Anyone who stops learning is old, whether at twenty or eighty. Anyone who keeps learning stays young. The greatest thing in life is to keep your mind young." - Henry Ford

[info] => Array

(

[quote_characters] => 156

[quote_words] => 28

[author_slug] => henry-ford

[author_count] => 62

[genre_name] => Age

[genre_slug] => age

[genre_count] => 998

)

=> Array

(

[filename] => henry-ford/jR.jpg

[size] => 82.2K

[width] => 885

[height] => 885

)

[.. SNIP ..]

[29] => Array

(

[id] => VM

[quote] => I don't feel old. I don't feel anything till noon. That's when it's time for my nap.

[author] => Bob Hope

[full_quote] => "I don't feel old. I don't feel anything till noon. That's when it's time for my nap." - Bob Hope

[info] => Array

(

[quote_characters] => 84

[quote_words] => 17

[author_slug] => bob-hope

[author_count] => 19

[genre_name] => Age

[genre_slug] => age

[genre_count] => 998

)

=> Array

(

[filename] => bob-hope/VM.jpg

[size] => 77.7K

[width] => 885

[height] => 885

)

100

)

101

102

)

103

104

)

Image API

When have a full featured API for manufacturing images in a number of formats (including animated GIFs), and the quotes returned as above might be used with the API to return branded images. All clients will receive a zip file of branded quotes very early in our relationship. For others, a collection of around 25,000, 75,000, or 100,000 images is available for a small fee.

The background images are either user-supplied or a specific collection is chosen (the sample image below comes from the "nature" gallery). The most recent iteration of our API now returns a blurred background image by default (with crisp text it generally makes the quote pop out of the page).

Sample image returned from the BeliefMedia Image Factory API

The Image Factory API will be discussed another time.

Sample PHP Function

The following function is an example of one that might be used to retrieve search results.

<?php

Quotes API

https://www.beliefmedia.com.au/quotes-api

function beliefmedia_entertainment($page = '', $number = '', $type = false, $search = false, $apikey = 'xxxxx') {

if ($page == '') $page = '1';

if ($number == '') $number = '20';

if ($type === false) $type = 'browse';

/* Correct for invalid search type */

$permitted_types = array('browse', 'search', 'author', 'genre');

if (!in_array($type, $permitted_types)) $type = 'browse';

$type = ($type == 'browse') ? 'browse' : 'type=' . $type . '&search=' . str_replace(' ', '+', $search);

$data = @file_get_contents('http://api.beliefmedia.com/platform/sources/quotes/quotes.json?apikey=' . $apikey . '&pg=' . $page . '&number=' . $number . '&' . $type);

if ($data === false) return false;

$data = json_decode($data, true);

if ($data === false) return false;

/* Likely return array of errors with code & message */

if ($data['code'] != '200') return $data['message'];

return (array) $data;

}

Usage (close the pre tags):

$result = beliefmedia_entertainment($page = '', $number = '', $type = false, $search = false, $apikey = 'xxxxx');

echo '

<pre>' . print_r($result, true) . '</pre>

$result = beliefmedia_entertainment($page = '', $number = '', $type = 'author', $search = 'mark-twain', $apikey = 'xxxxx');

echo '

<pre>' . print_r($result, true) . '</pre>

$result = beliefmedia_entertainment($page = '2', $number = '', $type = 'genre', $search = 'age', $apikey = 'xxxxx');

echo '

<pre>' . print_r($result, true) . '</pre>

A single result requires just the quote itemid and apikey.

Considerations

Searching by character count, word count etc. are all available, but their use is beyond the scope of this article.
Every now and again we'll make a small collection of branded images available at no cost to our Facebook or mailing list following.
A WordPress plugin is available to return paginated quote results in a WP website. We have another PHP script that is essentially a 'turnkey' quotes website. Both products work best with locally hosted images.
Most of what's quoted on the Internet is what we wanted people to say, not what they actually said. Einstein and Marilyn Monroe are probably two of the hardest hit by distorted or fake attribution. However, short quotes are often a paraphrased sentiment, giving them a certain truth.