Calling the services

The non-visual services are plain .NET classes. They work the same in WPF, WinForms, Blazor and MAUI apps, including server-side code. Each one takes a provider and an optional API key in its constructor and returns a ServiceResult<T>.

The services are included in the Trial package you installed in the Quick Start, so there is nothing extra to install.

Warning

Do not add TMS.Maps.Services or another individual TMS.Maps.* package next to a .Trial package. The Trial package already contains them, and the two conflict.

The result pattern

Every service call returns a ServiceResult<T>. Use IsError(out var data) to branch: it returns true when the call failed (or produced no payload) and hands you the payload otherwise.

using TMS.Maps.Core.Extensions;   // GetErrorMessages()

var result = await geocoding.GetAsync("1600 Amphitheatre Parkway, Mountain View, CA");

if (result.IsError(out var matches))
{
    Console.WriteLine(result.GetErrorMessages());
    return;
}

// 'matches' is guaranteed non-null here.
foreach (var m in matches)
    Console.WriteLine(m.FormattedAddress);

Geocoding

Forward (address → coordinates) and reverse (coordinates → address) geocoding via GeocodingService.

using TMS.Maps.Core.Extensions;
using TMS.Maps.Core.Models;
using TMS.Maps.Geocoding;

using var geocoding = new GeocodingService(Providers.Google, "YOUR_API_KEY");

// Forward geocoding
var forward = await geocoding.GetAsync("Eiffel Tower, Paris");
if (!forward.IsError(out var places))
{
    var first = places.First();
    Console.WriteLine($"{first.FormattedAddress}: {first.Coordinate.Latitude}, {first.Coordinate.Longitude}");
}

// Reverse geocoding
var reverse = await geocoding.GetAsync(new Coordinate(48.8584, 2.2945));
if (!reverse.IsError(out var addresses))
    Console.WriteLine(addresses.First().FormattedAddress);

Directions

Calculate routes between two points (or a full DirectionsRequest) with DirectionsService.

using TMS.Maps.Core.Models;
using TMS.Maps.Directions;

using var directions = new DirectionsService(Providers.Google, "YOUR_API_KEY");

var origin = new Coordinate(37.7749, -122.4194);   // San Francisco
var destination = new Coordinate(34.0522, -118.2437); // Los Angeles

var result = await directions.GetAsync(origin, destination);
if (!result.IsError(out var routes))
{
    var route = routes.First();
    foreach (var leg in route.Legs)
        Console.WriteLine($"{leg.Distance} m, {leg.Duration} s");
}

Elevation

Resolve elevation for one or many coordinates via ElevationService.

using TMS.Maps.Core.Models;
using TMS.Maps.Elevation;

using var elevation = new ElevationService(Providers.Google, "YOUR_API_KEY");

var result = await elevation.GetAsync(new Coordinate(27.9881, 86.9250)); // Everest
if (!result.IsError(out var points))
    Console.WriteLine($"{points.First().Elevation} m");

Places

Search for points of interest with PlacesService, passing a PlacesRequest.

using TMS.Maps.Core.Models;
using TMS.Maps.Core.Models.Services;
using TMS.Maps.Places;

using var places = new PlacesService(Providers.Google, "YOUR_API_KEY");

var request = new PlacesRequest(
    Query: "coffee",
    RequestType: PlacesRequestType.TextSearch,
    Location: new Coordinate(40.7128, -74.0060),
    Radius: 1500);

var result = await places.GetAsync(request);
if (!result.IsError(out var hits))
    foreach (var place in hits)
        Console.WriteLine(place.Name);

Static maps

Build a static map image URL, or download the image bytes, with StaticMapService.

using TMS.Maps.Core.Models;
using TMS.Maps.Core.Models.Services;
using TMS.Maps.StaticMap;

using var staticMap = new StaticMapService(Providers.Google, "YOUR_API_KEY");

// Just need a URL (e.g. to bind to an Image source)?
string url = staticMap.GetUrl(new Coordinate(51.5074, -0.1278));

// Or download the rendered image.
var request = new StaticMapRequest(new Coordinate(51.5074, -0.1278), Width: 800, Height: 600, Zoom: 13);
var result = await staticMap.GetAsync(request);
if (!result.IsError(out var imageStream))
{
    await using var file = File.Create("map.png");
    await imageStream.CopyToAsync(file);
}

Location

Resolve the current device / IP location with LocationService.

using TMS.Maps.Core.Models;
using TMS.Maps.Location;

using var location = new LocationService(Providers.IPStack, "YOUR_API_KEY");

// Current caller's location
var result = await location.GetAsync();

// …or look up a specific IP address
var byIp = await location.GetByIpAsync("8.8.8.8");

if (!result.IsError(out var loc))
    Console.WriteLine($"{loc.Coordinate.Latitude}, {loc.Coordinate.Longitude}");

Choosing a provider by capability

Not every provider supports every service. Filter providers by capability with ProviderExtensions:

using TMS.Maps.Core.Attributes;
using TMS.Maps.Core.Extensions;
using TMS.Maps.Core.Models;

// Which providers can do directions?
foreach (var p in ProviderExtensions.GetProvidersByCapability(ProviderCapabilities.Directions))
    Console.WriteLine(p);

// Does the chosen provider support elevation?
bool ok = Providers.Google.SupportsElevation();

See also the API reference for the full set of overloads and result types.