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
Functions
Section titled “Functions”searchLocations()
Section titled “searchLocations()”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.
| Parameter | Type | Description |
|---|---|---|
apiKey | string | Google API key with the Places API (New) enabled, for example This.$Config.<name>.serverApiKey. |
query | string | Search text, for example an address or 'gas station Zurich'. |
options | LocationSearchOptions | Optional. Language, region and filters. |
LocationSearchOptions fields
| Field | Type | Required | Description |
|---|---|---|---|
language | string | No | Language of the results, for example 'de'. |
region | string | No | CLDR region code, for example 'ch'. Influences the results but does not restrict them. |
includedType | string | No | Google place type to restrict the results to, for example 'gas_station'. |
maxResults | number | No | Maximum number of results, 1 to 20. Defaults to 5. |
locationBias | { center: { lat: number; lng: number }; radiusMeters: number } | No | Prefers results within this circle. |
const apiKey = This.$Config.MyGoogleMaps.serverApiKeyconst [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()
Section titled “getLocationByPlaceId()”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).
| Parameter | Type | Description |
|---|---|---|
apiKey | string | Google API key with the Places API (New) enabled. |
placeId | string | Google place ID. |
options | Pick<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()
Section titled “reverseGeocode()”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.
| Parameter | Type | Description |
|---|---|---|
apiKey | string | Google API key with the Geocoding API enabled. |
latLng | { lat: number; lng: number } | The point. |
options | Pick<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()
Section titled “planRoute()”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.
| Parameter | Type | Description |
|---|---|---|
apiKey | string | Google API key with the Routes API enabled. |
waypoints | Types.GoogleMapsRouteWaypoints | Start, vias and destination. start and destination are required; otherwise the call throws. |
options | RoutePlanningOptions | Optional. Optimization target, traffic and route restrictions. |
RoutePlanningOptions fields
| Field | Type | Required | Description |
|---|---|---|---|
optimizeFor | 'distance' | 'time' | No | Whether the chosen route is the shortest or the fastest. Defaults to 'distance'. |
timeDependent | boolean | No | If true, considers traffic at the departure time. Google bills these requests at a higher rate. Defaults to false. |
departureTime | Date | null | No | Departure time for time-dependent routing. Ignored otherwise. Defaults to now. |
avoidTolls | boolean | No | Avoids toll roads. Defaults to false. |
avoidHighways | boolean | No | Avoids highways. Defaults to false. |
avoidFerries | boolean | No | Avoids ferries. Defaults to false. |
language | string | No | Language code passed to the Routes API. |
region | string | No | Region 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 / 1000Returns: Promise<Types.GoogleMapsRouteResult> · Availability: Server
createRouteImage()
Section titled “createRouteImage()”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.
| Parameter | Type | Description |
|---|---|---|
config | GoogleMapsConfig | A Google Maps configuration, typically This.$Config.<name>. |
route | Types.GoogleMapsRouteResult | The route to draw, for example from planRoute(). |
options | RouteImageOptions | Optional. Size, style and what to draw. |
GoogleMapsConfig fields
| Field | Type | Required | Description |
|---|---|---|---|
serverApiKey | string | null | No | API key used for the request. |
apiKey | string | null | No | Used if serverApiKey is empty. If both are empty, the call throws. |
mapId | string | null | No | Map ID whose cloud-based styling is applied to the image. |
RouteImageOptions fields
| Field | Type | Required | Description |
|---|---|---|---|
signingSecret | string | No | URL signing secret from the Google Cloud console. Recommended in production. |
width | number | No | Width in pixels, at most 640 before scaling. Defaults to 640. |
height | number | No | Height in pixels, at most 640 before scaling. Defaults to 400. |
scale | 1 | 2 | No | 2 returns an image of twice the size, for high-resolution displays. Defaults to 2. |
format | 'png' | 'jpg' | No | Image format. Defaults to 'png'. |
mapType | 'roadmap' | 'satellite' | 'terrain' | 'hybrid' | No | Map type. Defaults to 'roadmap'. |
language | string | No | Language of the map labels. |
region | string | No | Region code for borders and labels. |
waypoints | Types.GoogleMapsRouteWaypoints | No | Waypoints to mark. Without it, only the start and end of the route are marked. |
includeShortestDirectRoute | boolean | No | If true, also draws the shortest direct route underneath the chosen route. |
routeColor | string | No | Color of the chosen route as 0xRRGGBB or 0xRRGGBBAA. Defaults to 0x1a73e8ff. |
shortestDirectRouteColor | string | No | Color 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()
Section titled “createRouteImageUrl()”createRouteImageUrl(config: GoogleMapsConfig, route: Types.GoogleMapsRouteResult, options?: RouteImageOptions): stringReturns 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.
| Parameter | Type | Description |
|---|---|---|
config | GoogleMapsConfig | A Google Maps configuration; see createRouteImage(). |
route | Types.GoogleMapsRouteResult | The route to draw. |
options | RouteImageOptions | Optional. Size, style and what to draw; see createRouteImage(). |
Returns: string · Availability: Server
decodePolyline()
Section titled “decodePolyline()”decodePolyline(encoded: string): LatLng[]Decodes a path in Google’s encoded polyline format, such as GoogleMapsRouteSummary.encodedPolyline, into its points.
| Parameter | Type | Description |
|---|---|---|
encoded | string | The encoded polyline. |
Returns: { lat: number; lng: number }[] · Availability: Server
encodePolyline()
Section titled “encodePolyline()”encodePolyline(path: LatLng[]): stringEncodes a list of points in Google’s encoded polyline format, with coordinates rounded to five decimal places.
| Parameter | Type | Description |
|---|---|---|
path | { lat: number; lng: number }[] | The points. |
Returns: string · Availability: Server
Related
Section titled “Related”- Sys.Types (
GoogleMapsGeoLocation,GoogleMapsRouteWaypoints,GoogleMapsRouteResultand related types) - Configuration Items
- Sys API overview