Share a route

Overview

POST /share turns a planned route into everything you need to send it to a phone or a car: a link that reopens the exact route, one-tap deep links into Google, Apple and Waze Maps, and a GPX file for sat-navs, Garmin devices and cycling computers. It can also text the link straight to a phone.

Authenticate with a key scoped to share — send it as an x-api-key header. Each call is billed as one share; texting a route (SMS) is a server-side action, see below.

Request

POST the route: an origin, a destination, optional waypoints, and the travel mode.

curl -X POST "https://api.goggleplaces.com/share" \
  -H "x-api-key: gk_live_pk_…" -H "content-type: application/json" \
  -d '{"origin":[-0.1287,51.5163],"destination":[-0.1419,51.5014],"mode":"drive"}'

Parameters

origin, destination — required; each is [lon, lat] or {lat, lon}. waypoints[] — up to 25 intermediate stops. mode — drive | cycle | walk | transit. name — a label used in the SMS and GPX. channel — set to sms to text the link. phone — E.164 (e.g. +447700900123), required when channel=sms.

Response

A canonical link, deep links for every maps app, and a GPX route.

{
  "share_url": "https://goggleplaces.com/route-planner?from=51.5163,-0.1287&to=51.5014,-0.1419&mode=drive",
  "google_maps_url": "https://www.google.com/maps/dir/?api=1&origin=…&destination=…&travelmode=driving",
  "apple_maps_url": "https://maps.apple.com/?saddr=…&daddr=…&dirflg=d",
  "waze_url": "https://waze.com/ul?ll=51.5014,-0.1419&navigate=yes",
  "gpx": "<?xml version=\"1.0\"?>…"
}

Send to phone & car

share_url reopens the route in the planner — ideal behind a QR code the user scans with their phone. The Google, Apple and Waze links open the route in the phone’s maps app, which is exactly what shows on CarPlay and Android Auto in the car. gpx imports into sat-navs, Garmin devices and cycling computers.

Text a route (SMS)

Add channel: "sms" and a phone number to text the link. SMS is a server-side action, so it uses a secret key (gk_live_sk_…); the message is sent from the GOGGLE sender ID.

curl -X POST "https://api.goggleplaces.com/share" \
  -H "x-api-key: gk_live_sk_…" -H "content-type: application/json" \
  -d '{"origin":[-0.1287,51.5163],"destination":[-0.1419,51.5014],
       "channel":"sms","phone":"+447700900123"}'

{ "share_url": "…", "sms": { "sent": true, "to": "+44770090••23" } }

SDK

import { shareRoute } from '@goggleplaces/sdk'

// links + GPX (publishable key, in the browser)
const s = await shareRoute({ key, origin, destination, mode: 'drive' })
//  s.share_url · s.google_maps_url · s.apple_maps_url · s.gpx

// text it (secret key, server-side)
await shareRoute({ key: secretKey, origin, destination,
  channel: 'sms', phone: '+447700900123' })

Billing

Billed under the share scope: a link / QR / deep-link / GPX share is one unit; an SMS bills as 100 units (£0.10 per text at the base rate). See Pricing.