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.
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 Web Site. 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 Web site.
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 Web site 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 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:
var marker = new StaticMap.Marker();
var map = new StaticMap
Width = 175,
Height = 175,
Zoom = 15,
LatCenter = 55.8592110,
LngCenter = -4.2466380
marker.Lat = map.LatCenter;
marker.Lng = map.LngCenter;
marker.Size = StaticMap.mSize.Normal;
marker.Color = StaticMap.mColor.Purple;
marker.Character = "1";
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.
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.
- 10th August, 2008: Initial post
- 14th August, 2008: Demo project updated to include a solution that will run with .NET Framework v2.0, on Visual Studio 2005. I no longer have Visual Studio 2005 installed, so there may be some issues with the 2005 solution file. The code however, will compile and run using the correct framework.