Map Scripting

Let’s say you have a lovely graphic of an area, like a downtown district or a park. It’s a flat, top-down view, like most maps. But it doesn’t quite match up with the streets or other features of a mapping API’s imagery. Before you can overlay your image, you’ll need to georeference it.

The process is also called rubber sheeting, because you are essentially stretching and manipulating your graphic so that every point of your graphic meets up with the appropriate geographic coordinates.

In the book I use Central Park as an example. I uploaded a graphic from a park brochure to a site called GeoWarper. Then I referenced parts of the graphic with other identifiable areas in an OpenStreetMap version of the same area. GeoWarper then spits out a georeferenced version of the graphic.

Want to try it out yourself? The original graphic is included above. You can start your own, or use mine. If you just want to see it completed, the warped graphic is also above and the Central Park map is in my examples section.

Many apps use zip codes to determine a user’s location. You can get the results with a geocoder service, or you can roll your own. From the same folks that supply the IP geolocation database, you can download one for U.S. zip codes.

The download is available as a direct database dump or CSV, like this:

"zipcode";"state";"fips_regions";"city";"latitude";"longitude"
"97002";"OR";"41";"Aurora";"45.2574";"-122.799"
"97005";"OR";"41";"Beaverton";"45.4924";"-122.803"

You’ll need to load it into a database and perform lookups yourself (ie, “select latitude, longitude from zips where zipcode=?”), but this is a good way to avoid wasting precious calls on fairly static and finite data.

Zip codes do change from time to time, so the database is updated periodically.

Looking for non-US postal codes? Check these out:

• UK postal codes

In addition to the W3C geolocation standard (I covered iPhone geolocation previously) and finding your user’s location based on IP, there are a number of services that let users actively share their whereabouts. Most of these services also have APIs, which allow you to access the shared locations (with the users permission, of course).

Here is a selection of location APIs and in some cases, tutorials that help you get started:

• FourSquare allows read and write actions. Check out the documentation and this PHP tutorial
• Google Latitude is in Beta and also allows read and write. See Google’s documentation.
• Gowalla only has a read API. See its documentation.
• BrightKite has a fully-featured read/write API. There’s a Python library and documentation.
• Finally, there’s FireEagle, Yahoo’s location broker service. I cover this one in the book, but you can also see my WebMonkey tutorial and the FireEagle documentation.

Which are your favorites? Am I missing any?

Searching within a specific distance of a point is a common mapping task. Yet, we rarely see the search area visualized, even though it’s rather easy to do. In the book I show two circle overlay methods: one approximates a circle with a polygon and the other overlays a graphic.

When using an image, you’ll want it to be a transparent PNG with the same width and height. The circle should just fit, so that it touches the edges of the graphic. The one I use in the example is swiped from Google Latitude and it’s on the left. Just right-click and choose the option to save the image.

You can also create your own image using the Google Charts API wizard, like the border-less orange graphic above. Use its URL as a starting point at the bottom of the wizard.

If you make a graphic yourself, you’ll need to ensure that the PNG’s background is transparent. Otherwise, there will be a white box around your circle. You can make the circle itself semi-transparent, or rely upon the mapping API to display an opaque file at a percentage of its opacity.

For a working example of the polygon circle overlay, see this geocoded tweet mashup.

Many GPS units and even some mobile phone apps produce a GPX file, which contains a list of saved coordinates. These are usually called “tracks” and are useful for sharing or re-purposing where you’ve been. In the book, I show how to plot tracks on a map.

The example from the book uses Portland’s Laurelhurst Park tracks (raw GPX file). If you’d like to create your own tracks with a mobile phone, check out My Tracks for Android or Trails for iPhone.

There are also sites to share GPX files, such as GPXchange.

For those who want a quick introduction to mapping on the web, I’ve offered my Start Here Guide for the last year. My full book is coming soon (did you know you can pre-order Map Scripting 101?), but the guide will remain. In fact, now it’s also available in Spanish.

I’m indebted to Claudio Cossio of Frontera Estates for not only the translation but the idea to offer a Spanish version in the first place. Thank you, Claudio!

So, regardless of whether you want it en ingles o en español, you can Download the Start Here Guide for free.

I presented a talk on moving beyond the typical map mashup today at SXSW Interactive in Austin. In it, I showed some simple ways to improve your maps, from using Mapstraction to custom map markers to changing the entire map imagery.

If you would like to get a feel for the presentation and examples, my “slides” are one giant HTML file. Really, it’s quite giant. So I’ve included the examples below. View the source, look around. Many of these are explained in detail in Map Scripting 101, but if you have questions I’d be happy to cover some more in-depth on this blog.

• Basic Google Map
• Basic Yahoo Map
• Google and Yahoo Swappable Map
• Custom marker icon
• Custom controls
• Custom zoom image controls
• Circle image overlay
• Click to connect Polylines
• Circle made of Polylines
• Austin Convention Center outline
• Central Park overlay
• Zelda world image overlay
• Geolocate your user

The pedometer community site Walker Tracker added a new feature that plots your steps on a route around the rim of the Grand Canyon–or a handful of other locations. And you can invite your friends on the trip, with each avatar shown at a location determined by the user’s step count.

This is the site’s first foray into using maps. Ben, the site’s founder, contracted me to write much of the code for the new feature. Walker Tracker has an active community of step-counters who already take part in a number of competitions on the site. I’m happy to see this new competition type go live into Beta.

I used the site’s API to grab the current competition results and convert steps into a distance. That turns out to be the easy part, as the average person travels a mile in 2,000 steps. So, to keep things fair, we used that constant. No advantage for the long-legged!

Finding out which leg of the journey a user is on was also fairly easy. Once I knew the user’s distance, I could keep a running total of each leg until the next point would make it further than the user’s distance. Then I knew the user was between two particular points. On some routes, the points could be many miles apart. Walker Tracker needed to be more precise than that.

Find a Point Along a Route

The mapping challenge here was to plot the walker at just the right point along the route. That turns out to be a fairly complex problem and the solution has become a section in my book.

The example above shows three points. It’s a two step process to find point X, 0.3 miles between points A and B:

1. Find the initial bearing (direction of travel) from point A to B
2. Using the bearing, determine the point 0.3 miles along the route between points A and B

As for how to calculate the bearing and the point along the route, these scripts from Movable Type were immensely helpful.

It might be the best way to make your map look different than all the others. Lose the reverse tear drop icons (the default Google look) and add your own graphics.

Mapstraction makes it easy to include your own markers. And, as always, write the code once in Mapstraction and it works in one of a dozen mapping APIs. Here’s a custom marker map demo that shows a sombrero over my favorite Mexican restaurant in Portland. Classy!

It looks something like this:

Now you try:

<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <title>Custom Marker Map</title>
    <script src="http://maps.google.com/maps?file=api&amp;v=2&amp;key=YOURKEY"
    type="text/javascript"></script>
    <script src="mapstraction.js"></script>
    <style>
      div#mymap {
        width: 400px;
        height: 350px;
      }
    </style>
    <script type="text/javascript">
      var mapstraction;
function create_map() {
  mapstraction = new Mapstraction('mymap', 'google');
  mapstraction.setCenterAndZoom(
    new LatLonPoint(45.559242, -122.636467), 15);
  var mk = new Marker(new LatLonPoint(45.559242, -122.636467));
  mk.setIcon('sombrero.png', [40,24]);
  mk.setShadowIcon('sombrero-shadow.png', [53,24]);
  mapstraction.addMarker(mk);
}
    </script>

  </head>
  <body onload="create_map()">
    <div id="mymap"></div>
  </body>
</html>

Remember you’ll need to download Mapstraction and get a Google Maps API key. Finally, make sure you have the following if you plan on using the sombrero images:

Happy mapping with your custom markers!

While we’re waiting for Twitter’s official geolocation platform, how about this ad hoc method. Pick a famous location, stick “at” in front of it, and use Twitter search.

Amber Case suggested Disneyland. Go ahead and try it out. I found that Graceland and Yellowstone have good results, too.

We’ll be able to do more interesting things when we have latitude and longitude. In the meantime, this is a fun, simple way to get a glimpse of what’s going on at popular vacation destinations.