If you're a C# .NET developer and want to get started using the new MapQuest 5.3 API then you can get started today with the beta/release candidate version available on http://developer.mapquest.com/Beta.
Download the .NET library and start exploring.

From a .NET point of view not much has changed (yet) in the 5.3 API:
- The library has been renamed to mapquest20.dll to reflect that this is for .Net 2.0 and above only
- It has been tested with the 2.0 framework AND the 3.5 framework
- It has been tested with both 32-bit and 64-bit environments
- No interface changes have been made

Getting a free developer account. Right now there are two types of developer account available:
- MapQuest Platform: Free Edition
- Free Developer License for MapQuest Platform: Enterprise Edition [1]

Just apply to the first one since that will give you access to both. After signing up and confirming your account, you may have to wait a couple of hours for your account to become active. Mine took about 6 hours to become active.

In the meantime you can download the .NET library. The whole library is contained in one DLL named mapquest20.dll, start a new project, add an assembly reference and you're ready to go.

Check your account confirmation email for a list of the server names that you can use to access the MapQuest Platform, note that the information in the email will be more accurate than what you may find on the beta website.

There are four MapQuest servers, each offering a unique set of services to make the MapQuest offering whole. These servers are:

  • Map Server - used for creating basic maps
  • Geocode Server - used for finding latitude/longitude for addresses
  • Route Server - used for created routes
  • Spatial Server - used for searching in a specific area

The C# API offers one central class which is responsible for all server calls and it is called the Exec class. Depending on what server you point the Exec class to the appropriate methods become available.

In order to produce a basic map you'll need at minimum the Map Server and probably the Geocode Server for locating an address.

One of the things you'll notice when using the mapquest20.dll is that it uses very few C#2.0 features (like generics). In order to make the provided API easier to use from my own code I've created some wrapper functions.
The first method can be used to geocode an address:


/// <summary>
/// Find a list of geo encoded addresses based on a regular adress.
/// </summary>
/// <param name="address">Address</param>
/// <returns>List of geocoded address, or null if none are available.</returns>
public List<GeoAddress> Geocode( Address address )
{
    Disposable.ClassVariableCannotBeNull( this, Exec, "Exec" );
    Parameters.NotNullOrEmpty( this, address.Country, "address.Country", "Geocode" );

    LocationCollection locations = new LocationCollection();
    try
    {
        Exec.Geocode( address, locations );
    }
    catch ( Exception exception )
    {
        // TODO: Log exception
        return null;
    }
    List<GeoAddress> results = new List<GeoAddress>( locations.Size );
    for ( int i = 0, size = locations.Size; i < size; i++ )
    {
        results.Add( (GeoAddress) locations.GetAt( i ) );
    }
    return results;
}

/// <summary>
/// Find a list of geo encoded addresses based on individual parts of an address.
/// </summary>
/// <param name="street"></param>
/// <param name="city"></param>
/// <param name="county"></param>
/// <param name="state"></param>
/// <param name="postalCode"></param>
/// <param name="country"></param>
/// <returns>List of geocoded address, or null if none are available.</returns>
public List<GeoAddress> Geocode( string street, string city, string county, string state, string postalCode, string country )
{
    Address address = new Address();

    address.Init();
    address.Street = street;
    address.City = city;
    address.County = county;
    address.State = state;
    address.PostalCode = postalCode;
    address.Country = country;

    return Geocode( address );
}

The second method will create an image based on the latitude/longitude of the point of interest. It will also show a basic point of interest at the specified location.

/// <summary>
/// Return a (bit)map centered on the provided address.
///
/// Address needs to have LatLng property set.
/// </summary>
/// <param name="address">The address to center on.</param>
/// <param name="width">Width of the map in pixels (DPI = 72)</param>
/// <param name="height">Height of the map in pixels (DPI = 72)</param>
/// <param name="scale">Scale of the map. Level of detail displayed varies depending on the scale of the map.</param>
/// <returns>Return a bitmap of the map centered on provided address.</returns>
public Bitmap GetMap( GeoAddress address, int width, int height, int scale )
{
    return GetMap( address.LatLng, width, height, scale );
}

/// <summary>
/// Return a (bit)map centered on the provided latitude/longitude.
/// </summary>
/// <param name="center">Coordinates for the center of the map.</param>
/// <param name="width">Width of the map in pixels (DPI = 72)</param>
/// <param name="height">Height of the map in pixels (DPI = 72)</param>
/// <param name="scale">Scale of the map. Level of detail displayed varies depending on the scale of the map.</param>
/// <returns>Return a bitmap of the map centered on provided latitude/longitude.</returns>
public Bitmap GetMap( LatLng center, int width, int height, int scale )
{
    // The MapState object contains the information necessary to display the map,
    // such as size, scale, and latitude/longitude coordinates for centering the map.
    MapState map = new MapState();

    // Define the width and height of the map in pixels.
    map.WidthPixels = width;
    map.HeightPixels = height;

    // The MapScale property tells the server the scale at which to display the map.
    // Level of detail displayed varies depending on the scale of the map.
    map.MapScale = scale;

    // Specify the latitude/longitude coordinate to center the map.
    map.Center = center;

    // The MapQuest Session object is composed of multiple objects,
    // such as the MapState and CoverageStyle.
    Session session = new Session();

    // Add objects to the session.
    session.AddOne( map );
    session.AddOne( Features.CreateBasicPOI(center) );

    sbyte[] imageBytes = Exec.GetMapImageDirect( session );
    byte[] bytes = (byte[]) (Array) imageBytes;

    MemoryStream stream = new MemoryStream( bytes );
    Bitmap bitmap = new Bitmap( stream );

    return bitmap;
}

The MapQuest API returns an image as an array of sbytes. Since .NET has a basic type for images, named Bitmap, it is much more useful to have the method return a bitmap which can then be used anyway you please. To do this the array is converted from sbytes to bytes since that is all the MemoryStream can handle.

The samples posted on the MapQuest site are a great help in figuring out how to use the C# MapQuest API and is actually more detailed than the provided documentation.

Happy coding!

- Mark Blomsma

[1] MapQuest Platform Services offers a free Developer License for Enterprise Edition, providing you access to the features and functionality of the Enterprise Edition while you are developing and prototyping your map application. Register for the free Developer License at MapQuest Developer Network and get started today.