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 billed separately — see Billing.

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

Link / QR / maps-deep-link / GPX shares bill under the share service — one unit each, with a free monthly allowance. Texting a route bills separately under share_sms: £0.10 per text, billed from the very first text — there is deliberately no free allowance for SMS, because each text carries a real per-message cost. Secret keys only. See Pricing.