Getting started

With the crowdsource nature of the pinball map application, it makes sense one does not need an API key to access the available data. Knowing this, it's pretty easy to get started accessing data from the API. In this guide, Javascript will be the language used for example code. For the most part, the focus of this guide will be utilizing Javascript to make HTTP requests and to handle the data coming back.

Some API endpoints require no manipulation to start getting data. For example, to fetch all regions, a simple 'GET' request to will return a JSON object of all the regions in the pinball map.

Other API endpoints require knowing specific values either obtained from the pinball map or by digging around within the API. Instances of these values have a colon before the tag of interest such as

To determine what regions are available to utilize the locations request, we can use the HTTP request to fetch all regions.

  var req = new XMLHttpRequest();'GET', '', false);
  var data = JSON.parse(req.responseText);

We get a regions object back from our request with the following information:


We are really interested in retrieving the names of the various regions for our purposes, so to do this, we can select the 'name' property from each region in the regions object and store the names in an easy-to-read array.

        var regions = [];
        for (region in data.regions) {


["dayton", "boise", "ottawa", "toronto", "sandiego", "michigan-west", "tampabay", "baltimore", "syracuse", "lasvegas", "utah", "hudsonvalley", "charleston", "maryland-north", "rochester", "oceancity", "reno", "southflorida", "orlando", "cleveland", "stlouis", "columbus", "nebraska", "iowa", "dfw", "nyc", "sacramento", "jacksonville", "spokane", "colorado", "chicago", "bakersfield", "dc", "louisville", "seattle", "bc", "kansascity", "phoenix", "houston", "newjersey", "burlington", "springfield", "philadelphia", "albuquerque", "asheville", "wisconsin", "tallahassee", "bellingham", "charlotte", "west-virginia", "central-indiana", "centralpa", "oregon-south", "massachusetts", "portland-maine", "birmingham", "richmond", "eugene", "champaign", "connecticut", "rhode-island", "new-hampshire", "bayarea", "la", "portland", "pittsburgh", "austin", "redding", "twincities", "detroit"]

Optional Query Parameters

Some of the API endpoints have optional paramaters which can be added to the request. For example, the 'GET' request of has several optional parameters including:

With the optional search parameters, we can optimize our searches for specific endpoints without much effort from our end. In order to utilize these optional parameters, they are added to the 'GET' request URL query string in the typical fashion of ?key1=value1&key2=value2

For example, this code will find all locations with 10 or more machines in the Portland region:

        var req = new XMLHttpRequest();'GET', '', false);
        var data = JSON.parse(req.responseText);

        var locations = [];
        for (var i=0; i<data.locations.length; i++) {


["BlackBird Pizza", "C-Bar", "Game Over Arcade", "Ground Kontrol Classic Arcade", "Pinball Outreach Project - POP HQ", "Scoreboard Sports Bar", "The Coin Jam"]

This list includes several locations though in the Portland region are in fact quite far from Portland, so we can narrow our search down more by including additional parameters such as a zone id. To include a zone id, we first we must determine the zone we want by fetching the zones in Portland by following the similar trend of an HTTP request to:

The response comes back as a zones object with an object for each zone:


After viewing the zones object, we can now recognize we're interested in the 'Southeast' zone which is zone 1. If we update our request in the previous code to be we now get the following locations with 10 or more machines:

["BlackBird Pizza", "C-Bar", "Scoreboard Sports Bar"]

Wrap Up

This wraps up the getting started portion of this guide. Hopefully you are recognizing trends of how to work with the data in this API. Now that we're comfortable with fetching data in different ways, let's put these techniques to use doing more exciting things!