Release history: see CHANGELOG.md.

GoogleMapsApi

A friendly, strongly-typed .NET wrapper for the Google Maps Web Services APIs — Geocoding, Routes, Directions, Distance Matrix, Elevation, Time Zone, Places, Address Validation, Solar, Aerial View, and Static Maps. Multi-framework (net10.0, net8.0, netstandard2.0 — the latter still covers .NET Framework 4.6.1+), async-first, and battle-tested with 2M+ downloads on NuGet.

Supported APIs

API	Description
Geocoding	Convert between addresses and geographic coordinates
Routes	Modern route planning — real-time traffic, eco-routing, toll calc, two-wheeled vehicles (replaces Directions)
Directions	Legacy route planning between two points with multiple travel modes
Distance Matrix	Travel time and distance between multiple origins/destinations
Elevation	Elevation data for individual locations or paths
Time Zone	Time zone information for any coordinate
Places (New)	Modern Places API — Text Search, Nearby Search, Place Details, Autocomplete, Place Photos
Address Validation	Validate a postal address with component-level confirmation; USPS CASS for US/PR
Solar	Building solar potential, roof geometry, panel layouts, financial analyses, and raster data layers (billable)
Aerial View	Render and look up cinematic flyover videos for US addresses
Static Maps	Generate URLs for static map images with markers, paths, and styles

Why this vs Google's official SDKs

Google's official .NET packages (e.g. Google.Maps.Routing.V2, Google.Maps.Places.V1) are auto-generated from gRPC service definitions — they're verbose, split across many packages, and feel like protobuf instead of .NET. GoogleMapsApi is a single, idiomatic NuGet package: one install, async-first, multi-target (modern .NET through legacy .NET Framework), with hand-crafted request/response types that read like normal C#. It also emits OpenTelemetry traces out of the box — something the official SDKs don't.

Installation

Install via NuGet Package Manager:

Install-Package GoogleMapsApi

Or via .NET CLI:

dotnet add package GoogleMapsApi

Looking for runnable examples? See samples/ — console, ASP.NET Core minimal API, and Blazor Server.

Quickstart

API Key Configuration

You can configure your Google Maps API key in several ways:

// Option 1: Set API key per request
DirectionsRequest directionsRequest = new DirectionsRequest()
{
    Origin = "NYC, 5th and 39",
    Destination = "Philadelphia, Chestnut and Walnut",
    ApiKey = "your-google-maps-api-key"
};

// Option 2: Set globally via app.config/appsettings.json (see wiki for details)

For more configuration options and detailed guides, see the wiki. Full API reference is published at maximn.github.io/google-maps.

Code Examples

Important

The static GoogleMaps facade was removed in 2.0.0, along with the legacy Places API (use Places (New)). Use the instance-based IGoogleMapsClient / GoogleMapsClient instead — construct it with an HttpClient (directly or via IHttpClientFactory / dependency injection). See Instance-based client below. Upgrading from 1.x? See the 2.0 migration guide.

Basic Usage (async-first)

using GoogleMapsApi;
using GoogleMapsApi.Entities.Common;
using GoogleMapsApi.Entities.Directions.Request;
using GoogleMapsApi.Entities.Directions.Response;
using GoogleMapsApi.Entities.Geocoding.Request;
using GoogleMapsApi.Entities.Geocoding.Response;
using GoogleMapsApi.StaticMaps;
using GoogleMapsApi.StaticMaps.Entities;

// Create a client backed by an HttpClient (reuse a single instance; IHttpClientFactory friendly)
using var http = new HttpClient();
var maps = new GoogleMapsClient(http, new GoogleMapsClientOptions { ApiKey = "your-google-maps-api-key" });

// Directions
DirectionsRequest directionsRequest = new DirectionsRequest()
{
    Origin = "NYC, 5th and 39",
    Destination = "Philadelphia, Chestnut and Walnut",
};

// Async call (recommended)
DirectionsResponse directions = await maps.Directions.QueryAsync(directionsRequest);
Console.WriteLine(directions);

// Geocode
GeocodingRequest geocodeRequest = new GeocodingRequest()
{
    Address = "new york city",
};
GeocodingResponse geocode = await maps.Geocode.QueryAsync(geocodeRequest);
Console.WriteLine(geocode);

// Static maps API - get static map of with the path of the directions request
StaticMapsEngine staticMapGenerator = new StaticMapsEngine();

//Path from previos directions request
IEnumerable<Step> steps = directions.Routes.First().Legs.First().Steps;
// All start locations
IList<ILocationString> path = steps.Select(step => step.StartLocation).ToList<ILocationString>();
// also the end location of the last step
path.Add(steps.Last().EndLocation);

string url = staticMapGenerator.GenerateStaticMapURL(new StaticMapRequest(new Location(40.38742, -74.55366), 9, new ImageSize(800, 400))
{
    Pathes = new List<GoogleMapsApi.StaticMaps.Entities.Path>(){ new GoogleMapsApi.StaticMaps.Entities.Path()
    {
            Style = new PathStyle()
            {
                    Color = "red"
            },
            Locations = path
    }}
});
Console.WriteLine("Map with path: " + url);

Routes API (modern replacement for Directions)

The Routes API is Google's modern replacement for the Directions API — it supports real-time traffic, eco-routing, toll calculation, two-wheeled vehicles, and route alternatives. Unlike Directions, it requires a field mask to constrain the response. A sensible default is pre-populated; tighten it to reduce response size and cost.

using GoogleMapsApi;
using GoogleMapsApi.Entities.Routes.Request;

using var http = new HttpClient();
var maps = new GoogleMapsClient(http, new GoogleMapsClientOptions { ApiKey = "your-google-maps-api-key" });

var request = new RoutesRequest
{
    Origin = Waypoint.FromAddress("San Francisco, CA"),
    Destination = Waypoint.FromAddress("Mountain View, CA"),
    TravelMode = RoutesTravelMode.Drive,
    RoutingPreference = RoutingPreference.TrafficAware,
    // FieldMask defaults to a Directions-equivalent shape; override to slim the response.
};

var response = await maps.Routes.QueryAsync(request);
var route = response.Routes![0];
Console.WriteLine($"{route.DistanceMeters} m, {route.DurationSeconds} s");

Solar API (building solar potential)

The Solar API returns a building's solar potential — roof geometry, panel layouts, expected energy production, and financial analyses — plus downloadable raster data layers (DSM, flux, shade). It is a billable API, so calls beyond the free tier incur charges.

using GoogleMapsApi;
using GoogleMapsApi.Entities.Solar.Request;

using var http = new HttpClient();
var maps = new GoogleMapsClient(http, new GoogleMapsClientOptions { ApiKey = "your-google-maps-api-key" });

// Solar potential for the building closest to a coordinate.
var insights = await maps.SolarBuildingInsights.QueryAsync(new BuildingInsightsRequest
{
    Latitude = 37.4450,
    Longitude = -122.1390,
});
Console.WriteLine($"Up to {insights.SolarPotential!.MaxArrayPanelsCount} panels");

// Discover raster data layers, then download one as raw GeoTIFF bytes.
var layers = await maps.SolarDataLayers.QueryAsync(new DataLayersRequest
{
    Latitude = 37.4450,
    Longitude = -122.1390,
    RadiusMeters = 50,
});
var dsm = await maps.SolarGeoTiff.QueryAsync(new GeoTiffRequest { Url = layers.DsmUrl! });
await File.WriteAllBytesAsync("dsm.tiff", dsm.Content);

Aerial View API (cinematic flyover videos)

The Aerial View API renders cinematic 3D flyover videos of US addresses. It has two operations, grouped under maps.AerialView: RenderVideo enqueues rendering (free), and LookupVideo fetches a video's state and signed media URIs (billable). Rendering is asynchronous and can take up to a few hours, so the typical flow is render once, then poll lookup by videoId with exponential backoff until the state is Active.

using GoogleMapsApi;
using GoogleMapsApi.Entities.AerialView.Request;
using GoogleMapsApi.Entities.AerialView.Response;

using var http = new HttpClient();
var maps = new GoogleMapsClient(http, new GoogleMapsClientOptions { ApiKey = "your-google-maps-api-key" });

// 1. Request a render (returns immediately; usually Processing on first call).
var render = await maps.AerialView.RenderVideo.QueryAsync(
    new RenderVideoRequest { Address = "500 W 2nd St, Austin, TX 78701" });
var videoId = render.Metadata!.VideoId!;

// 2. Poll until the video is ready (use a real backoff; rendering can take hours).
var video = await maps.AerialView.LookupVideo.QueryAsync(new LookupVideoRequest { VideoId = videoId });

if (video.State == VideoState.Active && video.TryGetUris(MediaFormat.Mp4High, out var uris))
    Console.WriteLine(uris!.LandscapeUri);

A looked-up video that does not exist (or has no 3D imagery available) returns HTTP 404, surfaced as an HttpRequestException. A still-rendering video is not an error — it returns State == VideoState.Processing.

Instance-based client (IHttpClientFactory-friendly)

GoogleMapsClient is the instance-based entry point that accepts an injected HttpClient. This is the standard pattern for ASP.NET Core, minimal APIs, and worker services — it plays nicely with IHttpClientFactory, per-instance event handlers, and an ambient API key that is auto-filled into requests when not set explicitly.

The companion package GoogleMapsApi.Extensions.DependencyInjection provides an AddGoogleMaps extension that registers the client through IHttpClientFactory and binds options in one call:

dotnet add package GoogleMapsApi.Extensions.DependencyInjection

// Register once at startup
services.AddGoogleMaps(options => options.ApiKey = "your-google-maps-api-key");
// …or bind from configuration (e.g. a "GoogleMaps" section in appsettings.json):
services.AddGoogleMaps(builder.Configuration.GetSection("GoogleMaps"));

// Inject and use
public class GeocodingService(IGoogleMapsClient maps)
{
    public Task<GeocodingResponse> LookupAsync(string address)
        => maps.Geocode.QueryAsync(new GeocodingRequest { Address = address });
}

AddGoogleMaps returns an IHttpClientBuilder, so you can chain resilience and other HttpClient configuration — e.g. .AddStandardResilienceHandler() from Microsoft.Extensions.Http.Resilience.

Prefer not to take the extra package? The core library still works with hand-wired DI:

services.AddHttpClient<IGoogleMapsClient, GoogleMapsClient>();
services.AddSingleton(new GoogleMapsClientOptions { ApiKey = "your-google-maps-api-key" });

Without DI:

using var http = new HttpClient();
var maps = new GoogleMapsClient(http, new GoogleMapsClientOptions { ApiKey = "your-key" });

var result = await maps.Directions.QueryAsync(new DirectionsRequest { Origin = "NYC", Destination = "DC" });

Per-instance events (no global state):

maps.Geocode.OnUriCreated += uri => uri;          // inspect/rewrite outgoing URI
maps.Geocode.OnRawResponseReceived += bytes => { }; // tap raw JSON

Synchronous Usage

The API is async-first. When you must call from a synchronous context, block on the task (prefer QueryAsync whenever possible):

DirectionsResponse directions = maps.Directions.QueryAsync(directionsRequest).GetAwaiter().GetResult();
Console.WriteLine(directions);

Observability (OpenTelemetry tracing)

Every API call emits a distributed-tracing span from an ActivitySource named GoogleMapsApi. There is nothing to enable on the library side — the instrumentation is inert (zero allocations) until a listener is registered, and lights up automatically once your tracing pipeline subscribes to the source.

With OpenTelemetry, add the source by name (the constant GoogleMapsApi.Diagnostics.GoogleMapsActivity.SourceName):

using OpenTelemetry.Trace;
using GoogleMapsApi.Diagnostics;

builder.Services.AddOpenTelemetry().WithTracing(tracing => tracing
    .AddSource(GoogleMapsActivity.SourceName) // "GoogleMapsApi"
    .AddOtlpExporter());

Each span is Client-kind, named GoogleMapsApi <Api> (e.g. GoogleMapsApi Geocoding), with its duration representing call latency. Tags follow OpenTelemetry HTTP semantic conventions plus a small gmaps.* set:

Tag	Example	Notes
gmaps.api	Geocoding	The Maps API invoked
http.request.method	GET / POST
server.address	maps.googleapis.com
url.full	…/geocode/json?...&key=REDACTED	API key and signature are always redacted
http.response.status_code	200
gmaps.response_status	OK / ZERO_RESULTS	Google body status, where the API exposes one

Failures set the span status to Error and add an error.type tag.

---

If this library saved you time, please ⭐ the repo — it helps others find it.