5.0: Evaluating an API for use in a Maproom

Often times, you are faced with the question on whether or not a particular API (not covered in class) can be used for your mapping purposes.  The following tutorial explains a typical workflow that will help you determine what data you might be able to access, and how to parse and evaluate its content for use (or not) within a Google Maps application.

*Note that this tutorial is a generic guide and is NOT applicable to all APIs.  APIs come in all sorts of formats and flavors, ie, each is different in its own regards.

We start with the assumption that you have found an organization that is making its data available to the public via an API.  The keyword here is “API”.  Most organization that share data will have a dedicated page for their API, and will have documentation regarding how to access their data.  Sometimes they will require an access key (which you will have to request), sometimes they will not.  However, the key questions to ask:

  • Do they provide data in JSON format?
  • Do they allow for JSONP?
  • Does the data include geographic parameters (latitude and longitude)?

For the purposes of this tutorial, and for the content of this course, we will focus on only those data providers that provide positive answers these three questions.

Step 1: Read their documentation

Every provider has a different set of rules on how to access their data.  Furthermore, they have their own set of guides on how their data is made available to the public.  Once you understand the logic of how their data feed works, you need to experiment with it to see if you can actually access it in your application.

Let’s take Oakland’s Crime Spotting API as an example.  Here is their page that explains their API:

http://oakland.crimespotting.org/api

The first thing you want to look for is an example of how to acquire their data.  They provide two example.  Taking their first one:

http://oakland.crimespotting.org/crime-data?format=tsv

You notice that this is a simple URL call that let’s you download their data in tsv format.  However, we want JSON format.  Changing the format parameter from “tsv” to “json” should solve this problem:

http://oakland.crimespotting.org/crime-data?format=json

Once you have gotten this far, it is time to see what this looks like when you access the data with javascript.

Step 2: Let’s get some JSON!

Start with an HTML document that brings in the jQuery library.  Here is a sample codeset:

Now create a new function that will bring in the data, and trace it:

Finally, add a call to run the function within the initialize function:

Step 3: What the JSON? Parsing the returned values…

Now that you have successfully gotten something BACK from a data provider, you need to figure out what to do with it.  The process of sifting through the returned values is called parsing.  Most data that is returned comes in one of 3 formats:

  • Objects
  • Arrays
  • Values

In order to effectively parse our return, we will use the Chrome browser’s console.  Our trace reveals the following:

The console is kind enough to tell us what is an object, and what is an array by simply labeling them as such.  It is also kind enough to color code the elements:

  • black tells us what type of data it is (object vs array),
  • purple tells us what the parameter (variable) name is given to us by the provider,
  • red tells us the text values for that record,
  • blue tells us the numeric values for that record

At the very top level, assuming that the feed provided is in JSON format, you will most certainly start off with an “Object”.  Expanding on this parent level object will reveal what is inside.  For this particular feed, we see that the first child element is “features: Array[20]”.

A rule of thumb on how to access values from a JSON feed:

  • . “period“: always use a period to access anything after an object
  • [ ] “square braquets”: always use square brackets to access any item within an array
  • “loop”:  use jQuery’s .each (loop) function to access each value within an array

In the feed shown above, we know that the first value following the object is:

  • features: Array[20]

This tells us that the object is returning an array variable “features” that has 20 items in it.

You are thus able to access each of the items in the array using an each loop:

Now you are tracing each individual feature being return. It is time to add some code to map it!

Leave a Reply