I originally published this article on Codeproject.com
Introduction
Unless you've been living on Mars for the past 4 years, you'll probably know about Google Maps and the rich API the lovely folks at Google have exposed, allowing all sorts of clever interactive mapping experiences that developers all over the world have been bringing to the masses.
In February 2008, Google went low key; it removed the JavaScript and the fancy API interface from Google Maps, and introduced the Google Static Maps API, allowing users the ability to generate a map as a regular image. It can still have markers and polylines, but is displayed as a static image, such as a JPEG, GIF, or PNG.
This article aims to explain how to use C# to implement the static images API using a fairly straightforward wrapper. If you've ever used the Google Maps API, this will be easy.
Cool, I get it, and I want some static map action on my website. Where do I start?
The static API is really, really easy to use. First off, you'll need a Map API key from Google. The one being used in the included demo code is for localhost.
You create a static map by adding an image to your HTML page. Then, by specifying a bunch of parameters in the image URL querystring, you can set the image size, location, zoom level, and a bunch of other parameters. The full spec is here.
In its simplest form, you can just create a static map by adding an image to an HTML page, and provided you have the correct information in the image URL querystring, you'll be able to add a map to a website.
Okay, thanks for that, can I go now?
Uh, no. Adding images using a parameterized URL is all good and well, but in the real world (well, my world at least), I really don't want to be messing around with querystrings. They are so 1995. If I have a large content managed website with 1000 geolocated points, I don't want to have to generate all that querystring information manually, it's way too prone to errors. I want databases, I want geocoded points, I want structure, in fact, what I need is a wrapper in C# that can handle the Static Maps API, then I can forget about querystrings, pipe-delimited parameters, and 1000 image URLs full of errors.
Using the code
A static map consist of two parts: the properties of the map image itself, such as the size, the zoom level, and the location, and the information displayed, which is a collection of markers and paths (static polylines for you gmapping aficionados). This article doesn't cover paths, the implementation is similar to adding markers. I might add it at a later date if people ask.
So, let's look again at a basic map with a marker attached:
To represent this in .NET then, we need a class containing a map, with properties defining the image dimensions, zoom level, centre point, and we need a class that contains the marker information (size, position, color, optional character).
Here's a class diagram that should cover it (I've edited this slightly to better fit on-screen):
Each map has the following properties:
- APIKey - Obtainable from Google, and required to render a map.
- Height: Image height in pixels.
- Width: Image width in pixels.
- LatCenter: The central latitude point of the map (the 'Y' axis).
- LngCenter: The central longitude point (the 'X' axis).
- Type: Mobile or Roadmap. The mobile maps generally use less key lines around roads, and often have more street names for the equivalent zoom level.
- A generic list of Markers. The nested Marker class contains information for each marker, such as the Lat/Lng points, marker size, color, and optional single character identifier (such as a letter or number).
Properties such as a the marker color, size, etc. are simply defined as enums - if Google adds any more colors or sizes at a later date, it is easy enough to extend.
For example, this code will create the image displayed in the article introduction:
// create new map object
var marker = new StaticMap.Marker();
var map = new StaticMap
{
Width = 175,
Height = 175,
Zoom = 15,
LatCenter = 55.8592110,
LngCenter = -4.2466380
};
// add marker to centre point
marker.Lat = map.LatCenter;
marker.Lng = map.LngCenter;
marker.Size = StaticMap.mSize.Normal;
marker.Color = StaticMap.mColor.Purple;
marker.Character = "1";
map.Markers.Add(marker);
// render map
imgMap.ImageUrl = map.Render();
Ultimately, on calling the Render method, the StaticMap class mashes together all its properties and its list of markers to generate a single parameterized URL used for generating a static map.
<img id="ctl00_ContentMain_imgMap"
src"http://maps.google.com/staticmap?center=55.859211,-4.246638&zoom=15&
size=175x175&maptype=roadmap&markers=55.859211,-4.246638,purple1&key="/>
I've included three examples in the downloadable demo that should explain how to use the class. It could be encapsulated into a usercontrol, or plugged into a larger CMS system where users get to position their point on a map, and choose the color and size of the markers. The only limit is your imagination.
In summary
The Static Maps API is a nice, simple way of creating Google maps that can be used in a multitude of places where a full blown, interactive, JavaScript enabled version just isn't required. Hopefully, this wrapper will make it easier for you to add them to your own projects without resorting to messing with querystrings.
History
Demo project updated to include a solution that will run with .NET Framework v2.0, on Visual Studio 2005. I no longer have VS2005 installed, so there may be some issues with the 2005 solution file. The code however, will compile and run using the correct framework.