google-maps

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, Air Quality, Pollen, 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
Air Quality	Current conditions, hourly forecast and history, plus heatmap tiles, for a coordinate (billable)
Pollen	Up to 5 days of daily pollen forecast (types and plants) plus heatmap tiles, for a coordinate (billable)
Static Maps	Generate URLs for static map images with markers, paths, and styles

Why this vs Google's official packages

Google ships official .NET packages primarily for its newer gRPC APIs — Google.Maps.Routing.V2, Google.Maps.Places.V1, Google.Maps.AddressValidation.V1, Google.Maps.Geocode.V4, and friends. For several classic REST web-service APIs (Distance Matrix, Elevation, Time Zone, Directions, Static Maps) there is no official .NET client at all — Google's maintained web-service client libraries cover only Java, Python, Go, and Node.js. Where both options exist, here's the honest trade-off:

Dimension	GoogleMapsApi	Google's official .V* packages
Classic REST web APIs (Distance Matrix, Elevation, Time Zone, Directions, Static Maps)	Typed support	No official .NET client exists
Packaging	One package (+ an optional DI package)	One NuGet per API
API surface	Hand-written, idiomatic C# request/response types	gRPC/protobuf-generated message types
Runtime dependencies	Lightweight: System.Text.Json on modern .NET; small compatibility helpers on netstandard2.0	gRPC stack: Google.Api.Gax.Grpc, Google.Geo.Type, Protobuf/gRPC dependencies; Grpc.Core on .NET Framework
Maturity	Stable 2.x, 2M+ downloads	Several Maps packages still in beta (1.0.0-betaNN)
DI / IHttpClientFactory	AddGoogleMaps(...) extension	ClientBuilder pattern; no IHttpClientFactory story
Observability	OpenTelemetry tracing span + metrics per call (API key redacted)	None built-in

Prefer Google's official packages when you need gRPC transport or streaming, deep integration with other Google Cloud client libraries, or Google's own support — and you only consume one of the gRPC-backed APIs. Otherwise, a single idiomatic package that also covers the web-service APIs is usually the friendlier choice.

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 — or the interactive notebooks (one live, runnable .dib per API surface).

Scaffold a project in 10 seconds

Spin up a working ASP.NET Core Web API (with /geocode and /directions endpoints) using the dotnet new template:

dotnet new install GoogleMapsApi.Templates
dotnet new googlemaps-webapi -o MyMapsApi --apikey YOUR_API_KEY
cd MyMapsApi && dotnet run

The key is written to appsettings.Development.json (gitignored), and the generated project references the matching GoogleMapsApi version. Pass -f net8.0 to target .NET 8.

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)

…

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.

…

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.

…

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.

…

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.

Air Quality API (current conditions, forecast, history, heatmap tiles)

The Air Quality API reports air-quality indexes, pollutant concentrations and health recommendations for a coordinate — as current conditions, an hourly forecast, or hourly history — plus PNG heatmap tiles. Opt into the richer fields with ExtraComputations. It is a billable API, so calls beyond the free tier incur charges.

…

Pollen API (daily forecast + heatmap tiles)

The Pollen API returns up to five days of daily pollen information — index values, in-season flags and descriptions for pollen types (grass, tree, weed) and individual plants — plus PNG heatmap tiles. It is a billable API, so calls beyond the free tier incur charges.

…

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 LookupAsync(string address)
        => maps.Geocode.QueryAsync(new GeocodingRequest { Address = address });
}

AddGoogleMaps returns an IHttpClientBuilder, so you can chain resilience and other HttpClient configuration. Google's APIs throttle with HTTP 429; rather than hand-rolling retries, add the standard Polly-backed resilience handler from Microsoft.Extensions.Http.Resilience:

dotnet add package Microsoft.Extensions.Http.Resilience

services.AddGoogleMaps(options => options.ApiKey = "your-google-maps-api-key")
        .AddStandardResilienceHandler();

The standard handler retries transient failures — including HTTP 429 (throttling), 408, and 5xx — with exponential backoff and a circuit breaker, so callers no longer need to wrap calls in retry logic.

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

services.AddHttpClient();
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 & metrics)

Tracing

Every API call emits a distributed-tracing span from an [ActivitySource](https://learn.microsoft.com/dotn