How to Use the Pinball Map API

It’s no secret that we have a public API. Or wait, maybe it kind of is, given how many people say to us, “I had no idea you had an API!” Point is, it’s not supposed to be a secret. After all, we link to it on the homepage (though not in the app, which is likely the problem here) and frequently mention it on the blog.

We get excited whenever anyone uses the API. And now, not only has someone used it, but she wrote a tutorial on how to use it! Beth Poore, a post-bacc in Computer Science at Oregon State University, used the Pinball Map API for a class project. For anyone looking to learn more about the API, this project is not only a great how-to guide, it’s also an illustration of the creative things you can do with the data (things that we don’t do on the Pinball Map website).

The tutorial covers a lot of ground:

- Querying data
- Post a list of your locations machines on your website
- Post high scores for your machines on your website
- Compare the machines in TWO regions
- Show national high scores

As you can see, you can do a lot with the data via the API. We’re excited to share Beth’s work with you all. Hope you find it useful!

How-To: Using the Pinball Map API

Using the Pinball Map API to list machines on your website

Here’s a simple example of using the Pinball Map API to do something cool. In this post I’ll give a detailed how-to (with PHP and jQuery examples) so that you can implement this feature on your site.

Background: http://pinballmap.com aims to actively promote pinball. If you own a business that carries publicly-playable pinball machines, then our site is free advertising for you.

Say you want to share on your own website that you have pinball machines. And you want to list the machines you currently have, AND you want that list to stay current without you having to update your website.

Well, that’s easy. You can pull that information from http://pinballmap.com using the Pinball Map API.

Here’s an example of it in action.

There’s a cool pinball spot in Los Angeles called Pins and Needles. They have a rotating list of around 20 machines. PNN’s website is made with WordPress.

Scott created an API endpoint specifically for listing a location’s machines (note: this is Ryan typing, and I’m not an expert on any of this stuff). Here’s what the raw json file looks like for PNN: http://pinballmap.com/api/v1/locations/4845/machine_details.json

Note the “4845” in the url. That is the location ID. To see the machine data for your site, you’ll have to replace 4845 in the url with your location’s ID. So now you should be asking, what is the location ID for my location?

That’s easy to find:

First go to the regional map that your location is in. For PNN that’s the Los Angeles Pinball Map

Then search for your location. When it comes up, click the link that says “Link to this map result”

That link has your location ID. In this case it’s http://www.pinballmap.com/la/?by_location_id=4845

4845! So, just plug that number (or rather, your number) into the json link above and you’ll see your machine data.

Parsing the json data, and putting in on your website

It might hurt your brain to stare at that json data. The important thing to know is that there’s an object called ‘machines’ and within it is an array of hashes. These are the keys in each hash: “name” “year” “manufacturer” “ipdb_link”. And each key has a value.

To spit out the data, you iterate through the hashes, pulling out the values you want along the way. In the PNN machines page, I used all of four of those values. There’s the name, and if you click the name it goes to the ipdb_link, and then in parentheses there’s the manufacturer and year.

Here’s a PHP method for spitting this out

In WordPress, you can create a page template and then place this code in it. Place this code near “the_content” (your mileage may vary).

So here’s the php code, with my comments explaining what everything does. At the bottom of this post is a link to the complete code, so you can copy it.

First grab the json file and decode it.

<?php
$url = "http://pinballmap.com/api/v1/locations/4845/machine_details.json";
$json = file_get_contents($url);
$data = json_decode($json, TRUE);

Then add a FOR loop that counts through the hashes.

for($i=0; $i<count($data['machines']); $i++) {

Then I created variables, so that the final part is easier to read

$link = $data['machines'][$i]["ipdb_link"];
$name = $data['machines'][$i]["name"];
$manufacturer = $data['machines'][$i]["manufacturer"];
$year = $data['machines'][$i]["year"];

And here’s the output

echo "<h4><a href=" . $link . ">" . $name 
. "</a> (" . $manufacturer . ($manufacturer? ", " : "") 
. $year . ")</h4>";
}
?>

If you want to only spit out the names of the machines, then “echo $name;” would do it.

(If you’re wondering about the conditional statement ($manufacturer? etc) – that’s there because some machine hashes do not contain values for the manufacturer field. So that conditional is saying "if there’s no manufacturer value, then don’t print that comma.)

jQuery Method

(In WordPress, you usually have to use “jQuery” rather than “$”.)

First add this div to the template, placing it near “the_content” (your mileage may vary).

<div class="machine_list"></div>

The results will print in that div. The code below should be within a script tag.

jQuery(document).ready(function() {

get the json file

jQuery.getJSON("http://pinballmap.com/api/v1/locations/4845/machine_details.json", function(data) {

create a loop

jQuery.each(data.machines, function(i, obj) {

Variables!

var machineName = data.machines[i].name;
var link = data.machines[i].ipdb_link;
var year = data.machines[i].year;
var manufacturer = data.machines[i].manufacturer;
var list = jQuery(".machine_list");

spit out the result!

jQuery("<h4 />", { html: "<a href=" + link + ">" + machineName
 + "</a> (" + manufacturer + (manufacturer? ", ": "") 
+ year + ")"}).appendTo(list);
});
});
});

Here’s the raw code for both methods

The result on the Pins and Needles website

Even if you don’t have a WordPress site, these methods will work. You just need a website that supports either PHP or jQuery.

So, now we never have to update that page on the Pins and Needles website! As long as the map is up to date, the website is up to date.

In conclusion, this is a simple way to post your machine list on your website. Tell me if you have any questions, and tell us if you use it on your website!

Pinball Map iOS App 3.0

We’re happy to announce a MAJOR update to the Pinball Map iOS app!

This is the first update in, uh, four years. A lot has happened in iOS-land in those years. New phones, new tablets, new native UI, new resolutions.

The original developer of the Pinball Map iOS app, Isaac Ruiz, put together a solid app that held strongly for years and was instrumental in growing pinballmap.com. The last version of the app (2.0) worked great and lots of people loved it, but it was missing some important features from the website. Over the last four years, we came up with a nice list of improvements for it. Just like the website, where we’re continuously rolling out updates and new features, we’re always looking for ways to improve the user experience. “Oh, a user didn’t know that they can REMOVE machines from locations? WHY didn’t they know that? Seems like we can probably improve the user interface/experience there.” But, we have limited resources! We (Scott and Ryan) work on the website basically every day (current count: we’ve committed code updates 1,340 times), and Scott does the entire the Android app and also spent time refactoring the iOS app.

Then along comes Frank Michael Sanchez! He’s an illustrious iOS developer who saw that the app was in serious need of modernization. He reached out to us and volunteered his service to it. And he immediately proved his expertise. Scott put together a new Pinball Map API, so that Frank Michael could easily access all the data in a clean and efficient manner. And Frank Michael rewrote the entire app starting from scratch. We worked closely with him to make sure that key features were added, and we had a squadron of regional administrators beta testing it. The entire time we knew the app was in good hands. And no joke, he put the entire update together in like three months!

As always, the app is free (and makes no money from ads). Frank Michael put in his time for free, all so we can supply a better experience to you folks who use the site/apps (and who support it by updating it). If you’re looking to hire an iOS developer for your project, hit him up! We can’t recommend him enough.

Pinball Map App 3.0 has a modernized interface, supports retina displays and has both iPhone AND iPad versions, and has new features. And we plan to roll out updates with regularity. Since the app was released yesterday, we’ve already received a bunch of feedback (send yours here). And yes, we’ll add back “recently added” in version 3.1!

New features:

  • iPad support, retina support, iPhone 5 support, new look, and MANY updated interface elements.
  • Offline access
  • Submit new locations to be added to your regional map!
  • When adding a machine to a spot, it’s now way easier to choose from the list of machines in the database.
  • You can add a “Location Type” tag to a spot. Like, if the location is a Laundromat, and isn’t already tagged as one, then you can add that tag. Then, when users “filter by location type” they can choose Laundromat and the spot you tagged will show up. (Not all locations are already tagged, because this is a feature we added later. The site will be cooler if ALL spots are tagged with a Type.)
  • Add phone numbers to locations
  • View manufacturer, year, and Internet Pinball Database information about a machine
  • In general, it’s easier to do a lot of things, like add/remove machines from locations, add machine condition comments, etc.

See more screenshots here.

The iOS and Android apps both play a humongous role in spreading the word about the site (and about pinball in general). It’s just nice to be able to carry it around with you, with a simple, intuitive interface (though if you don’t have a mobile device that supports either app, please note that we added a simple mobile skin to the website – try it out!). Thanks for using the site/apps to support your regional pinball map.

Get the updated Pinball Map iOS App!

pinballmap.com API V1

Hello Pinballers,

We’re pleased to present to you, the pinball public, version 1.0 of the pinballmap.com API. This is the API that we’re using to power our Android and iPhone apps (look for huge new releases of both of those applications in the near future, btw). It’s our hope that by putting the public closer to the data behind the map, that we can all work together to build new and exciting views into the pinball landscape of these United States.

API documentation is available here:
http://pinballmap.com/api/v1/docs

If there are any features or endpoints that you feel are missing from this API, please submit patches for them here:
https://github.com/scottwainstock/pbm

…or request that someone make them for you via our Portland admin contact form, here:
http://www.pinballmap.com/portland/about

This API is stable with its current offerings, but expect additions to V1 to roll out in the next couple months. Please let us know if you any of the current documentation or functionality is unclear.

Let the data mining begin! All we ask is that you let us know if you end up doing something cool with the data, because we like seeing cool stuff with this data too!

Some ideas of things maybe you’d like to do with this data…

  • A windows phone app
  • A website showing what machines are the most popular, by region
  • A “high high score board”, showing the top scores nationwide
  • Data validation tools to help ensure that locations on the map are still in business

…I dunno, SOMETHING. We’ve only got so many hands and brains over here, let’s work together.

Yours in pinball,
The cats and staff of PBM