Skip to content

Sys.GoogleMaps

Sys.GoogleMaps calls Google Maps web services from server-side code: place search (Places API (New)), reverse geocoding (Geocoding API), car route planning (Routes API) and static route images (Maps Static API). The API key usually comes from a Configuration Item of type “Google Maps” (This.$Config.<name>), whose serverApiKey is meant for these server-side calls and is never sent to the client.

Requests carry the app’s public URL as Referer header, so an API key restricted to HTTP referrers also works from the server. A failed request throws an error with Google’s HTTP status and message.

Availability: Server

searchLocations(apiKey: string, query: string, options?: LocationSearchOptions): Promise<Types.GoogleMapsGeoLocation[]>

Searches places and addresses by free text with the Places API (New) text search, and returns the matches with coordinates.

ParameterTypeDescription
apiKeystringGoogle API key with the Places API (New) enabled, for example This.$Config.<name>.serverApiKey.
querystringSearch text, for example an address or 'gas station Zurich'.
optionsLocationSearchOptionsOptional. Language, region and filters.

LocationSearchOptions fields

FieldTypeRequiredDescription
languagestringNoLanguage of the results, for example 'de'.
regionstringNoCLDR region code, for example 'ch'. Influences the results but does not restrict them.
includedTypestringNoGoogle place type to restrict the results to, for example 'gas_station'.
maxResultsnumberNoMaximum number of results, 1 to 20. Defaults to 5.
locationBias{ center: { lat: number; lng: number }; radiusMeters: number }NoPrefers results within this circle.
const apiKey = This.$Config.MyGoogleMaps.serverApiKey
const [location] = await Sys.GoogleMaps.searchLocations(apiKey, 'Bahnhofstrasse 1, Zürich', {
language: 'de',
region: 'ch',
maxResults: 1,
})

Returns: Promise<Types.GoogleMapsGeoLocation[]>; places without coordinates are left out · Availability: Server

getLocationByPlaceId(apiKey: string, placeId: string, options?: Pick<LocationSearchOptions, 'language' | 'region'>): Promise<Types.GoogleMapsGeoLocation | null>

Looks up a place by its Google place ID, for example the placeId of a GoogleMapsGeoLocation, with the Places API (New).

ParameterTypeDescription
apiKeystringGoogle API key with the Places API (New) enabled.
placeIdstringGoogle place ID.
optionsPick<LocationSearchOptions, 'language' | 'region'>Optional. language and region, as for searchLocations().

Returns: Promise<Types.GoogleMapsGeoLocation | null>; null if the place has no coordinates · Availability: Server

reverseGeocode(apiKey: string, latLng: LatLng, options?: Pick<LocationSearchOptions, 'language' | 'region'>): Promise<Types.GoogleMapsGeoLocation>

Finds the address of a point with the Geocoding API. If Google finds no address, the result contains only the coordinates.

ParameterTypeDescription
apiKeystringGoogle API key with the Geocoding API enabled.
latLng{ lat: number; lng: number }The point.
optionsPick<LocationSearchOptions, 'language' | 'region'>Optional. language and region, as for searchLocations().

Returns: Promise<Types.GoogleMapsGeoLocation>, with placeId and formattedAddress if an address was found · Availability: Server

planRoute(apiKey: string, waypoints: Types.GoogleMapsRouteWaypoints, options?: RoutePlanningOptions): Promise<Types.GoogleMapsRouteResult>

Plans a car route from start through the vias to destination with the Routes API, with the same rules as the route picker component. Use it, for example, to check a GoogleMapsRouteResult that a client submitted.

Besides the chosen route, the result contains the shortest direct route from start to destination, without vias, so that you can detect detours. With optimizeFor: 'distance', Lowgile requests alternatives for each leg and keeps the shortest; this makes one Routes API request per leg plus one for the direct route.

ParameterTypeDescription
apiKeystringGoogle API key with the Routes API enabled.
waypointsTypes.GoogleMapsRouteWaypointsStart, vias and destination. start and destination are required; otherwise the call throws.
optionsRoutePlanningOptionsOptional. Optimization target, traffic and route restrictions.

RoutePlanningOptions fields

FieldTypeRequiredDescription
optimizeFor'distance' | 'time'NoWhether the chosen route is the shortest or the fastest. Defaults to 'distance'.
timeDependentbooleanNoIf true, considers traffic at the departure time. Google bills these requests at a higher rate. Defaults to false.
departureTimeDate | nullNoDeparture time for time-dependent routing. Ignored otherwise. Defaults to now.
avoidTollsbooleanNoAvoids toll roads. Defaults to false.
avoidHighwaysbooleanNoAvoids highways. Defaults to false.
avoidFerriesbooleanNoAvoids ferries. Defaults to false.
languagestringNoLanguage code passed to the Routes API.
regionstringNoRegion code passed to the Routes API.

The shortest direct route always ignores traffic, but uses the same avoid… options. If no route is found for a leg, the call throws.

const route = await Sys.GoogleMaps.planRoute(
This.$Config.MyGoogleMaps.serverApiKey,
{ start: fromLocation, vias: [], destination: toLocation },
{ optimizeFor: 'time', avoidTolls: true },
)
const km = route.chosenRoute.distanceMeters / 1000

Returns: Promise<Types.GoogleMapsRouteResult> · Availability: Server

createRouteImage(config: GoogleMapsConfig, route: Types.GoogleMapsRouteResult, options?: RouteImageOptions): Promise<Buffer>

Renders the chosen route of a GoogleMapsRouteResult as a map image with the Maps Static API, styled by the configuration’s mapId if it is set. Waypoints are marked with the letters A, B, C, …; start and destination in red, vias in orange. Long routes are simplified so that the request URL stays within Google’s length limit.

ParameterTypeDescription
configGoogleMapsConfigA Google Maps configuration, typically This.$Config.<name>.
routeTypes.GoogleMapsRouteResultThe route to draw, for example from planRoute().
optionsRouteImageOptionsOptional. Size, style and what to draw.

GoogleMapsConfig fields

FieldTypeRequiredDescription
serverApiKeystring | nullNoAPI key used for the request.
apiKeystring | nullNoUsed if serverApiKey is empty. If both are empty, the call throws.
mapIdstring | nullNoMap ID whose cloud-based styling is applied to the image.

RouteImageOptions fields

FieldTypeRequiredDescription
signingSecretstringNoURL signing secret from the Google Cloud console. Recommended in production.
widthnumberNoWidth in pixels, at most 640 before scaling. Defaults to 640.
heightnumberNoHeight in pixels, at most 640 before scaling. Defaults to 400.
scale1 | 2No2 returns an image of twice the size, for high-resolution displays. Defaults to 2.
format'png' | 'jpg'NoImage format. Defaults to 'png'.
mapType'roadmap' | 'satellite' | 'terrain' | 'hybrid'NoMap type. Defaults to 'roadmap'.
languagestringNoLanguage of the map labels.
regionstringNoRegion code for borders and labels.
waypointsTypes.GoogleMapsRouteWaypointsNoWaypoints to mark. Without it, only the start and end of the route are marked.
includeShortestDirectRoutebooleanNoIf true, also draws the shortest direct route underneath the chosen route.
routeColorstringNoColor of the chosen route as 0xRRGGBB or 0xRRGGBBAA. Defaults to 0x1a73e8ff.
shortestDirectRouteColorstringNoColor of the shortest direct route. Defaults to 0x5f636888.
const image = await Sys.GoogleMaps.createRouteImage(This.$Config.MyGoogleMaps, route, {
waypoints: route.waypoints,
includeShortestDirectRoute: true,
format: 'jpg',
})

Returns: Promise<Buffer>, the image data · Availability: Server

createRouteImageUrl(config: GoogleMapsConfig, route: Types.GoogleMapsRouteResult, options?: RouteImageOptions): string

Returns the Maps Static API URL that createRouteImage() requests, without requesting it. The URL contains the API key, so don’t pass it to End users unless the key is meant for the browser.

ParameterTypeDescription
configGoogleMapsConfigA Google Maps configuration; see createRouteImage().
routeTypes.GoogleMapsRouteResultThe route to draw.
optionsRouteImageOptionsOptional. Size, style and what to draw; see createRouteImage().

Returns: string · Availability: Server

decodePolyline(encoded: string): LatLng[]

Decodes a path in Google’s encoded polyline format, such as GoogleMapsRouteSummary.encodedPolyline, into its points.

ParameterTypeDescription
encodedstringThe encoded polyline.

Returns: { lat: number; lng: number }[] · Availability: Server

encodePolyline(path: LatLng[]): string

Encodes a list of points in Google’s encoded polyline format, with coordinates rounded to five decimal places.

ParameterTypeDescription
path{ lat: number; lng: number }[]The points.

Returns: string · Availability: Server

  • Sys.Types (GoogleMapsGeoLocation, GoogleMapsRouteWaypoints, GoogleMapsRouteResult and related types)
  • Configuration Items
  • Sys API overview