More fun with APIs

22 August 2006

After playing with the Timeline API last week, and having reasonable success, I thought I’d try another widget this week.

As a result, AotW now has another new feature: a Gazetteer for the Maryland Campaign of 1862. Please go try it and let me know what you think.

AOtW screenshot of Gazetteer map
AotW Gazetteer screenshot

My gazetteer is an index of towns, structures, and geographic features–about 70 places so far–most often mentioned in the literature of the Campaign. Some are archaic names not found on modern maps, some are just hard to find. All are listed as links below a lovely GoogleMap.

Click a name on the list and we plot and center the location on the map.

I don’t intended this map to supplant the campaign or battle maps already on AotW. But I expect this would be a useful tool for someone trying to follow the action reading a book or other document on the campaign. Or someone planning a trip to the area, and plotting places to see. Or looking at the relationships between two or more points of interest.

Each location is (or will eventually be) tagged with additional information and links to associated events or people. This information is presented as a pop-up window on demand.

The map behaves in the ways you’d expect of a Google Map, so I hope it will be easy, even intuitive, to use.

I have been accumulating geo-data for towns and features in the AotW database for some time now, not knowing exactly how to use it. With the Google Maps API it was a fairly simple leap to put these places on a map. I’d like eventually to make more sophisticated use of both the data and the mapping API, but for now I’m happy with this fairly specific function.



  • The Google Maps API is well documented and supports/is supported by a huge community of developers and other users. There’s plenty of help out there.
  • I was up most of last Sunday night making all this work. Went round and round and round … the final code looks trivial to me now, but it wasn’t automatic.
  • Like Perl, there are many ways to code something in Javascript. It turns out, also, that some of the Google calls I needed are “undocumented” and others did not work as I thought they should. Being open to trial-and-error and cribbinglearning from what others have done were key for me here.
  • I’m not blaming Google or Javascript for my difficulties, per se. I hate Javascript, but it’s me, not it. Google is doing great things in this arena – my thanks to them.
  • I used PHP code to pull the locations and geo-data from the database and write the Javascript used to invoke the API and its functions. I pass data between the html and the map on the link URLs. A little fat, perhaps, but effective. I tried several other methods. Too hard.
  • If you view-source on my Javascript, please comment by private email and save me the public embarrassment, won’t you?

3 Responses to “More fun with APIs”

  1. Jim Studnicki says:


    Good stuff. For CW applications, I find the USGS 24K topo maps to often be the most useful (e.g., for locating cemeteries), and they’re unfortunately missing from the Keyhole / Google Earth dataset. The TIGER USGS dataset is implemented by (an oldie but goodie) and you can search all of its place / names there.

    I wrote a similar integration to Google Earth’s data awhile back, except I’m directly rendering KML as a link off of my existing location pages. You’ve got to have Google Earth installed, of course, but I’d already written my own front-end to the TerraServer data and didn’t feel the need to re-invent the wheel.

    One problem I have with user-entered data on Google Earth is that it’s not globally searchable (unless they’ve changed it lately; last time I checked you could post links to your .kml files on a message boards of sorts but its usefulness was extremely limited). I understand the reason — any user-entered content provides an entry point for spam, and for garbage / incorrect data to be entered — but if Wikipedia can demonstrate that the model can work, it can be done.

    The most immediate application I can see for this is a proximity-based application where one can be shown all existing markers inside the current window once inside a certain zoom range. Think of popping up markers on each monument within the current 100m square of the battlefield, or plotting all cemeteries with CW interments within x miles.

    — Jim

  2. William J. Turkel says:

    Brian, pretty sweet! I haven’t had a chance to play with it yet, but MetaCarta has a placename API that might be useful.

  3. Harry says:


    Checked it out, played with it, and I dig it.

    BTW, the timeline still doesn’t work for me. Has anyone else had trouble with it?

Please Leave a Reply