11:59pm Thomas Mapfumo & The Blacks Unlimited “Chikonzero (The Reason Why)” from Chimurenga '98
11:56pm Sleater-Kinney “Hurry On Home” from The Center Won't Hold
11:52pm Deportees “Time Is the Tiger” from Re-dreaming - EP
(Updated 08:27:28 UTC)
Coming up later today
5:00am Truth and Justice Radio
10:00am Sunday Morning Country
Spinitron API demo in PHP
Source code for this demo web site is on Github
In the yellow box, the recent spins and upcoming shows use API data.
When the server generates this page, it renders two PHP partial views,
These fetch data from the API and render it as HTML.
seconds with an Ajax request to
The files in this demo are organized as follows:
├── app │ ├── getClient.php │ └── SpinitronApiClient.php ├── cache └── www ├── css ├── index.php ├── recent.php └── today.php
apphas a simple caching client class for the Spinitron v2 API and a script that instantiates it with your API key.
cacheholds the temporary cache data files.
wwwhas this page and the two partial views
Try it yourself
If you have a computer with PHP, you can run this demo locally and modify it:
- Download and upzip the zip file (or clone the repo)
- Create a file
api-key.txtin the root directory (beside the
wwwdirectories) containing your API key, which you can find in the admin area of Spinitron v2
- Open a command shell and in the
wwwdirectory start a test PHP web server:
php -S localhost:8000
- Go to
http://localhost:8000/in a browser.
To use this approach in your web site, adapt the examples in the
Make sure the
are outside your web server's document root. If you move the
www then update the line that includes
in the partial views.
SpinitronApiClient.php is not complex so if you know PHP, take a look.
How it works
index.php is this page. It is ordinary HTML with only two interesting parts. First,
<div class="widget-box"> block are two PHP blocks that render the
today.php into this page as it is loaded.
Second, at the bottom of the page is
<div id="spin-recent"> block every five seconds.
today.php are partial views, which means they output
fragments of HTML to be placed inside something else. In our case the fragments are put into
<div> blocks on this page.
recent.php. First it loads the client. Next it
uses the client to get data from the API. Finally it uses a
loop to generate a number of
<p> elements, each containing text describing a recent spin.
today.php is very similar.
If you have the test web server running, as described above, you can view the output of these partial views in your browser by navigating to and viewing the page source of the following URLs:
Both partial views use the following line to bootstrap a
include __DIR__ . '/../app/getClient.php';
getClient.php instantiates a
using your API key and saves it to the global variable
It offers simple generic methods
fetch() to get
data from the API.
recent.php loads the most recent three songs
$client->search('spins', ['count' => 3]) and
today.php loads the upcoming schedule in a similar way.
SpinitronApiClient itself for more detail—it's not complex.
See also the API documentation.
The two partial views
getClient.php, which provides a
- use the client to get data from Spinitron,
- generate fragments of HTML (to display the data) as output.
The main web page
- on initial page load, inserts the HTML fragments output by the partial views into the page using PHP
replace the list of recent spins with freshly loaded output of
recent.phpevery five seconds.
SpinitronApiClient doesn't collect garbage, i.e. it does not delete expired cache files.
If, like this demo, all your queries use static parameters, e.g.
['end', '+6 hour'], then you don't
need garbage collection since stale cache files will not proliferate.
But if your queries have variable parameters, e.g. date-times, then you probably need it.
Searching through cache files to find expired ones can take time so it's good to decouple it from
page request processing, which is the only time
SpinitronApiClient is used in this demo.
SpinitronApiClient collects cache files together according to their lifetimes.
The name of each top level directory in the cache is the expiration time in seconds of
the cache files it contains, e.g.
/var/www/v2-api-demo/cache ├── 30 │ └── spins?count=3 └── 900 └── shows?end=%2B6+hour
This allows other programs to figure which files are expired.
For example, I put this in
/etc/cron.hourly of the Debian system running this demo
(not that the demo actually needs it)
#!/bin/bash d=/var/www/v2-api-demo/cache for f in `ls $d`; do let m=($f+59)/60 find "$d/$f" -type f -mmin +$m -delete done
SpinitronApiClient is very basic. It has no dependencies and should work on older
versions of PHP. It was designed to demonstrate making API requests and file caching so you could
adapt it to your needs. It is not supposed to be a robust API client. Feel free to use it if it
works for you but consider also using
other API and HTTP clients.
Spinitron's terms of service require that you have access credentials in order to use the API and that you don't share them with other entities. We also require that you use a cache. This demo uses a file-based cache.
As always, for support contact Eva at Spinitron on 617 233 3115 or by email at email@example.com.