Using Google Maps with the Formstack API

Written by Ade Olonoh on September 5, 2007

Posted in Form Hacks

The Formstack API is now live, and available to anyone with an account. To create a key to use with your forms, log in to the admin interface, go to Your Account then click on the API section. We’ve put together some online documentation to help you get started, along with some example PHP code (more languages coming soon).

In this article, I’m going to walk you through an overview of the creation of a mashup application that uses the Formstack and Google Maps APIs. It’s the first of three Google mashups that we’ve put together this week to help programmers better understand the API, and hopefully spark some creative ideas on ways you can use Formstack with other web applications. Today’s mashup will take addresses submitted with a form and display the locations on an interactive map. For example, if you create a registration form for an event you’re holding, you can use this to easily display where your registrants are coming from. Feel free to download the source code and follow along.

The first thing to do is create your form with the appropriate address fields. The one used in this example has text fields for address, city and zip code, and a select list for U.S. states.


Now you’ll need to create an API key with data access to that form. Log into your account as described above to create the key. You’ll also need to create a Google Maps API key in order to geocode the addresses and display the map.

There are a lot of ways to use the Google Maps API, but what we’re going to do in this example is create a static HTML file with JavaScript code that displays the map, while the points on the map are fetched from an XML file. The file will be generated with a PHP script that gets submitted form entries, sends each address to the Google Map geocoder to translate them to a latitude/longitude point, and outputs something like this:


In the PHP script (data.php in the download), we’ll first make a request to the API’s form method to get information about all the fields on the form, in order to map field ids to labels (e.g., so we know the City field is the field with ID 100001).

// Get information on the Formstack form
$form = Formstack::request($api_key, 'form',
    array( 'id' => $form_id ));
// Map field ids to labels
$fields = array();
foreach ($form['fields'] as $field) {
    $fields[$field['id']] = $field['label'];

Now we make a second request to the API to retrieve submitted entries from the form:

// Get the 1st page of submitted data for the form
$data = Formstack::request($api_key, 'data', array('id' => $form_id));
// Iterate over each entry
foreach ($data['submissions'] as $submission) {
    // ...

As we loop over each submission we create a geocoder query string by combining address, city, state and zip code values. We’re going to request a CSV formatted response from the geocoder, which is described in detail here.

// Make a request to Google's geocoder to get address lat/long
$csv = file_get_contents('' .
    urlencode($address) . '&output=csv&key=' . $maps_key);
// Parse the first line of the CSV response
$lines = explode("n", $csv);
$res = explode(',', $lines[0]);
// Add this point if the status code was successful
if ($res[0] == 200)
    print ''."n";

Now that the XML file is being generated with points for each address, you need to create the HTML and JavaScript to display the map. In the HTML file, you can start with the Hello World example from the Google Maps API documentation. Now use the GDownloadUrl() method to point to data.php, parse the XML and add a marker for each entry:

GDownloadUrl("data.php", function(data, responseCode) {
    var xml = GXml.parse(data);
    var markers = xml.documentElement.getElementsByTagName("marker");
    for (var i = 0; i < markers.length; i++) {
        var point = new GLatLng(
        map.addOverlay(new GMarker(point));

Once that’s done, you should have a map that looks something like the image below (this shows all the Starbucks within a 2 mile radius of our offices):


If you use this on a live site, you might want to setup a cron job to run the PHP script and save the output to a static XML file every few minutes, then point to that file instead. That would speed up the rendering process dramatically, and ensure that you don’t reach the maximum number of requests for your API keys if the site gets heavy traffic.

That’s all. Feel free to comment if you have any questions or suggestions. Check back tomorrow for another example.