Developers
API ReferenceDeveloper Portal

API

Maps and flight watches

Live aircraft, flight history, saved maps and places, flight watches, notification groups, web push, and Find My.

See Maps. Find My (/v1/me/findmy) is the person's own, from the Maps apps: never a key or another app's sign-in.

Every route below, with its parameters, request and response, errors and samples, is in the API reference.

RouteWhat it does
GET /v1/hooks/maps/shared/:tokenA map shared by link, with its places. No authentication; owner and organization aren't included.
GET /v1/hooks/maps/p/:tokenAn event's public position page (the link texts and emails give recipients outside the platform): the event's title, time, time zone and position, and until when the page follows the aircraft. No authentication; no watch, organization or recipient details. 410 once the link has expired (7 days).
GET /v1/hooks/maps/p/:token/liveWhere that event's aircraft is now (position, altitude, speed, track), from the live picture, for 2 hours after the event: aircraft is null while it isn't seen, live: false after that. Only that one aircraft. No authentication; rate-limited per link.
POST /v1/hooks/maps/eta-linkA shared trip's link (docs/maps/directions.md → A link for someone without an account): { token } in the body, so the token stays out of request lines and logs. The trip as someone it's shared with sees it, the sharer's name alone; 404 for anything a link doesn't open; 429 with Retry-After past maps.eta.linkOpensPerHour from one address.
POST /v1/hooks/maps/eta-progressA shared trip's progress from the sharer's phone with Maps closed (docs/maps/directions.md → With Maps closed), with the trip's own key (Authorization: Bearer si_eta_…), never the person's token; the body as /v1/me/findmy/eta/:tripId/progress. { status, endsAt }; 401 for an unknown key or a signed-out phone, 409 once the trip has ended or the sharer hides their location (the phone stops on either), 429 past the hourly limits per key and, for unknown keys, per address.
GET /v1/hooks/maps/eta-progressWhether the key's trip still runs: { status, endsAt }, else as above. The phone asks when Maps opens; nothing is kept.
GET /v1/hooks/maps/notify/:tokenA notification recipient's status (pending, active, unsubscribed) and group name. No authentication: the token is the recipient's own.
POST /v1/hooks/maps/notify/:token/confirmConfirms a recipient (double opt-in). No authentication.
POST /v1/hooks/maps/notify/:token/unsubscribeUnsubscribes a recipient (RFC 8058 one-click: mail clients post here from the List-Unsubscribe header). No authentication.
POST /v1/hooks/maps/locationA background location report from the Maps app with the phone's key (Authorization: Bearer si_loc_…; the body as for …/report). The key writes only its phone's fix and works only while that phone's sign-in does: 401 otherwise, and the phone's location is deleted. 204 when dropped (one report per 20 s is stored).
GET /v1/orgs/:orgId/maps/cars{ cars }: the cars you see, where you may see them (Vehicles' sharing rules), with their state, battery and picture. Empty where Vehicles isn't available.
POST /v1/orgs/:orgId/maps/cars/trailsWhere the cars you see have been (docs/maps/timeline.md → Trails): each car's drive so far, or its last drive when it parked recently, as Vehicles shows it to you; null for a car with nothing to show (whatever the reason). Each ask says what you hold, so the answer has only what's new.
GET /v1/orgs/:orgId/maps/timelineOne page of what happened between from and to (ISO dates or epoch milliseconds, at most 31 days): { range, items, sources, next?, keeps }. sources (vehicles, flights, people; all by default) picks what is read. next.to asks for the earlier part.
GET /v1/orgs/:orgId/maps/layers{ layers: { photos, events, traffic, tasks } }: which of the map's other layers you may turn on here (docs/maps/layers.md): scopes and the org's app switches.
GET /v1/orgs/:orgId/maps/layers/photos/:photoIdA photo's card on the map: { photo: { photoId, kind, takenAt, thumbUrl? } }, for one of your own located photos.
GET /v1/orgs/:orgId/maps/layers/:layerA layer's things (LayerAnswer): photos (your own, in bbox), events (your events from yesterday to a month ahead, at their places), traffic (your organisation's Cloud traffic by country, the last 7 days) or tasks (your organisation's Tasks issues with a place in bbox, as you can open them in Tasks; spaces (keys) and status (todo, inprogress, done) filter them, open work by default). bbox is west,south,east,north; the answer's box says what it covers (everywhere for events and traffic). state: "off" where it isn't yours to see here.
GET /v1/orgs/:orgId/maps/timeline/drives/:vehicleId/:tripIdA drive on the timeline with its track, for playback: as Vehicles' drive detail answers it, for a drive you see.
POST /v1/orgs/:orgId/maps/timeline/roadsDrives' lines on the roads they took ({ drives: [{ vehicleId, tripId }] }, up to 50): { roads: { [tripId]: stretches | "pending" | null } }. Display only.
POST /v1/orgs/:orgId/maps/directionsDirections (docs/maps/directions.md): { from, to, mode } (drive with live traffic, walk, cycle) answers { routes } (the best and up to two alternatives, with steps; a drive's traffic) or { error: "no_route" | "too_far" | "unavailable" }. POST, so the points stay out of URLs and logs; they go to Mapbox for this request only. Counted per person per hour (maps.directions.routesPerHour): past it, 429 with Retry-After.
GET /v1/orgs/:orgId/maps/roads{ on, available }: whether you draw drives on the roads they took (on unless you turned it off), and whether there are drives here.
PUT /v1/orgs/:orgId/maps/roadsDraws drives on the roads they took, or as driven ({ on }): your choice, shared with Vehicles' Display.
GET /v1/orgs/:orgId/maps/configWhat the apps need to draw: the ADS-B source and its credit line, preset areas, event types, channels (mobile, web, email, sms, call: available or not, and their labels), what a new watch gets by default for the caller (defaults: events, channels, smsEvents), the Mapbox public token for the native map with the Referer it may need (mapbox), and for texts whether the SMS account is still in the provider's sandbox and where the caller's own texts go (masked). For circling and approach alerts: aircraft classes, enabled aircraft presets, the org's locations, circling sensitivity presets and approach defaults. units: the caller's units for measurements (the org's setting with their own on top; /settings).
GET /v1/orgs/:orgId/maps/settingsMaps settings: the units measurements show in (speed kt | km/h | mph, altitude ft | m, distance nm | km | mi). units is what the caller sees, org.units the org's setting and mine.units the caller's own (each only what it sets; unset is knots, feet, nautical miles).
PUT /v1/orgs/:orgId/maps/settingsThe org's units, for everyone without their own (org owners and admins, or a key, with maps:write). A unit left out goes back to the default.
PUT /v1/orgs/:orgId/maps/settings/meThe caller's own units, in every org, over the org's ({ units: null } follows the org again). People only.
GET /v1/orgs/:orgId/maps/aircraftLive aircraft inside bbox (west,south,east,north), from the flight poller's latest snapshot: position, barometric altitude (null on the ground), ground speed, track, vertical rate, callsign, registration, type, squawk, icon class and, with trails=1, the last 15 minutes of track. Also returns the source, its credit line and the areas polled. Views outside the polled areas are added to the poller's areas for a few minutes.
GET /v1/orgs/:orgId/maps/aircraft/nearestThe nearest aircraft in the air to a point, and the next two (the phone's nearest-aircraft widget): which way each is from the point (bearingDeg, compass), how far (rangeM), its altitude (ft), speed (kt), track and phase, and, while it descends, when it should land (landing.at, unix seconds) and at which airport when one lies ahead on its track. The point is rounded to about 100 m and never stored or logged; like a map view, an area outside the polled ones is covered for a few minutes from now (pending until it is). units: the caller's Maps units, for showing the numbers.
GET /v1/orgs/:orgId/maps/aircraft/searchAircraft in the live snapshot by ICAO hex, registration or callsign (q; exact matches first, then prefixes).
GET /v1/orgs/:orgId/maps/aircraft/:hexOne aircraft wherever it is, with its recent track: live from the snapshot (live: true), else its last known position and the track before it from recorded positions (live: false, lastSeen), or aircraft: null when nothing is known. When it isn't live the poller looks it up by hex for a few minutes (pending).
GET /v1/orgs/:orgId/maps/aircraft/:hex/trackRecorded track of a watched aircraft over the last hours (0.25–24, default 6): points [seconds, lon, lat, altitude ft | null, ground speed kt, track°], oldest first. Positions are recorded only while a watch covers the aircraft (kept 14 days).
GET /v1/orgs/:orgId/maps/listsSaved maps the caller can see: their own, and those shared with the organization or by link. With places=1, each map includes its places.
POST /v1/orgs/:orgId/maps/listsCreates a saved map: name, optional description, pin color (chart-1…chart-5, foreground), icon and sharing (private, org, link).
GET /v1/orgs/:orgId/maps/lists/:listIdA saved map with its places.
PATCH /v1/orgs/:orgId/maps/lists/:listIdRenames a map or changes its description, pin style or sharing. sharing: "link" returns a shareToken for the public link; rotateLink: true replaces it; any other sharing turns the link off. Owner, or an org admin for shared maps.
DELETE /v1/orgs/:orgId/maps/lists/:listIdDeletes a map and its places.
POST /v1/orgs/:orgId/maps/lists/:listId/placesAdds a place: name, lat, lon, optional note, address, and its own pin color and icon.
PATCH /v1/orgs/:orgId/maps/lists/:listId/places/:placeIdChanges a place; moveTo moves it to another of your maps.
DELETE /v1/orgs/:orgId/maps/lists/:listId/places/:placeIdRemoves a place.
GET /v1/orgs/:orgId/maps/watchesFlight watches the caller can see (their own and those shared with the organization).
POST /v1/orgs/:orgId/maps/watchesCreates a flight watch: name, targets ({ kind: hex | registration | callsign | type, value }, a trailing * matches prefixes; no_callsign, any (value *) and class (helicopter, light, turboprop, jet, heavy, glider, balloon, drone) match inside areas only and need one; preset names an aircraft preset), exclude (the same shape: aircraft matching any never match, e.g. callsign POL3* except POL31), areas ({ kind: "preset", id: "au-vic" }, circles { center: [lon, lat], radiusKm }, polygons { ring: [[lon, lat], …] }, an org location { kind: "location", locationId, radiusKm } or { kind: "near_me", radiusKm } around the owner's phone, which makes the watch personal: private, the owner's only, no groups or people), limitToAreas, events (on/off per event type; approach and overhead need a location or near-me area), settings (signal, orbit with maxAltitudeFt, loiterMinutes and ignoreAirportsKm, approach, roads, thresholds), notify (channels: mobile, web, email, sms, call, with the older push read as mobile and web; includeOwner, groupIds, userIds (org members), liveActivity (an iOS Live Activity from takeoff to landing for recipients with mobile push, on by default), liveActivityPeople (per recipient user id: quiet, without alerts, or off; everyone else gets alerts), smsEvents, smsFormat, smsPrefix, cooldownMinutes, timeZone, quietHours), identity (mode: any or pin_first; pinnedHex), lifetime (startsAt, endsAt or forHours, maxNotifications, maxFlights, schedule with days, start, end, timeZone) and log (enabled, retentionDays, null for forever). Type targets match inside the watch's areas. Left out, every event is on and channels are the caller's defaults (GET …/maps/config → defaults). The maker gets a confirmation by push when they're a recipient. See Maps → Flight watches for every setting and its default.
GET /v1/orgs/:orgId/maps/watches/:watchIdA flight watch with every setting, defaults filled in. A near-me watch without a current location reads status: "waiting_location".
GET /v1/orgs/:orgId/maps/watch-peopleThe people a watch's recipients reach with mobile push, who can get its Live Activity (the editors' list): includeOwner (0 or 1), groupIds and userIds (comma-separated), personal (1: a near me watch) and watchId (whose owner is the owner; else the caller). people (owner first, with owner, named and groups) and hiddenGroups, whose members only their owner and admins see.
PATCH /v1/orgs/:orgId/maps/watches/:watchIdChanges a watch: fields sent replace the stored ones (nested objects whole; a notify without membershipNotices, liveActivity or liveActivityPeople keeps them). Owner, or an org admin for shared watches.
PATCH /v1/orgs/:orgId/maps/watches/:watchId/live-activitySets who gets the watch's Live Activity, keeping every other setting: liveActivity (the watch's switch; off ends running ones) and people, per recipient user id: alerts (the default), quiet (no sound, vibration or expanded Dynamic Island) or off (none; a running one ends). People left out keep theirs. Choices are for the watch's recipients: its owner, people named and group members.
POST /v1/orgs/:orgId/maps/watches/:watchId/pausePauses a watch: the poller stops evaluating it and nothing is sent.
POST /v1/orgs/:orgId/maps/watches/:watchId/resumeResumes a paused watch.
POST /v1/orgs/:orgId/maps/watches/:watchId/restartStarts an ended watch again (it ended at its end time, or after its notification or flight limit) with its counters at zero. A watch whose end time has passed needs a new one (or none) first.
POST /v1/orgs/:orgId/maps/watches/:watchId/testSends the caller a sample alert on the watch's channels that reach them and returns what each did: mobile (devices: phones with the Maps app, queued), web (sent, devices), email (sent), sms (sent, or skipped with why) and call (skipped). People only; maps:write, or the watch's owner.
GET /v1/orgs/:orgId/maps/watches/:watchId/flightsFlights the watch logged, newest first: airframe (hex, registration, callsign, type), start (takeoff or first_seen) and end (landing, lost, left, watch_ended, schedule), status (in_progress, completed, ended), distance, highest altitude, events and roads followed. hex filters to one airframe; pass the returned cursor for older ones.
GET /v1/orgs/:orgId/maps/watches/:watchId/flights/:flightIdOne logged flight with its track (points: [seconds, lon, lat, altitude ft | null, ground speed kt, track°]).
GET /v1/orgs/:orgId/maps/watches/:watchId/flights/:flightId/exportA logged flight as a file: format=gpx (track and events as waypoints), kml (line and time-stamped track) or csv (one row per position, events alongside).
DELETE /v1/orgs/:orgId/maps/watches/:watchIdDeletes a watch and its flight logs. Its events expire after 30 days.
GET /v1/orgs/:orgId/maps/watches/:watchId/eventsA watch's events, newest first (kept 30 days): type, aircraft, position, text, and what happened to the notification (sent with channels, quiet, no_recipients, failed). Pass the returned cursor for older ones.
GET /v1/orgs/:orgId/maps/eventsRecent events across the watches the caller can see, newest first.
GET /v1/orgs/:orgId/maps/incidentsEmergency incidents and warnings (Australia), from the incidents poller's picture: filtered to a view (bbox), hazards (hazards=bushfire,flood) and a minimum level (minLevel); sorted by distance from near=lon,lat (adds distanceKm), else most severe first; areas=0 leaves out warning areas (lists); limit. feeds carries each feed's credit line and licence. Answers 304 to a matching If-None-Match.
GET /v1/orgs/:orgId/maps/incidents/feedsThe emergency feeds in use: credit lines, licences, when each was last read and whether it's working.
GET /v1/orgs/:orgId/maps/incidents/:incidentIdOne incident (or its last version if it has ended) with its history of changes, newest first.
GET /v1/orgs/:orgId/maps/zones/configHazards, levels, zone events, states and a new zone's defaults for the caller.
GET /v1/orgs/:orgId/maps/zonesWatch zones: areas where emergency incidents and warnings alert (those the caller can see).
POST /v1/orgs/:orgId/maps/zonesCreates a watch zone: areas (circle, polygon, location, near_me or state; up to 10), hazards (empty: all), minLevel, events and notify (channels, people, groups, smsEvents, smsMinLevel, quiet hours with allowLevels). Channels left out get the caller's defaults.
GET /v1/orgs/:orgId/maps/zones/:zoneIdOne watch zone, with its status (active, paused or waiting_location for a near-me zone without a current location).
PATCH /v1/orgs/:orgId/maps/zones/:zoneIdChanges a watch zone (its owner, or an org admin for org zones): fields sent replace the stored ones.
POST /v1/orgs/:orgId/maps/zones/:zoneId/pausePauses a watch zone: nothing is checked or sent until it's resumed.
POST /v1/orgs/:orgId/maps/zones/:zoneId/resumeResumes a paused watch zone.
POST /v1/orgs/:orgId/maps/zones/:zoneId/testSends the caller a sample alert on the zone's channels that reach them; per-channel results.
GET /v1/orgs/:orgId/maps/zones/:zoneId/eventsA watch zone's alerts, newest first (limit, cursor): the change, the incident as it was, the distance and what was sent. Kept 30 days (7 for near-me zones).
DELETE /v1/orgs/:orgId/maps/zones/:zoneIdDeletes a watch zone. Its alerts expire on their own.
GET /v1/orgs/:orgId/maps/zone-eventsRecent zone alerts across the zones the caller can see.
GET /v1/orgs/:orgId/maps/locationsThe org's alert locations: locationId, name, lat, lon, siteRadiusM (within it counts as on site), address, note, icon, color, ownerId.
POST /v1/orgs/:orgId/maps/locationsCreates an alert location: name, lat, lon, siteRadiusM (50–5,000 m, default 300), optional address, note, icon, color. Up to 50 per organization.
GET /v1/orgs/:orgId/maps/locations/:locationIdOne alert location.
PATCH /v1/orgs/:orgId/maps/locations/:locationIdChanges an alert location; fields sent replace the stored ones. Moving it moves every watch that uses it. Its owner or an org admin.
DELETE /v1/orgs/:orgId/maps/locations/:locationIdDeletes an alert location. 409, naming them, while watches use it. Its owner or an org admin.
GET /v1/orgs/:orgId/maps/locations/:locationId/watchesWatches that alert near a location (watchId, name), those the caller can see.
GET /v1/orgs/:orgId/maps/groupsNotification groups with counts of active, pending and unsubscribed recipients.
POST /v1/orgs/:orgId/maps/groupsCreates a notification group (name).
GET /v1/orgs/:orgId/maps/groups/:groupIdA group and, for its owner and org admins, its recipients.
PATCH /v1/orgs/:orgId/maps/groups/:groupIdRenames a group.
DELETE /v1/orgs/:orgId/maps/groups/:groupIdDeletes a group and its recipients. Watches that used it stop sending to them.
POST /v1/orgs/:orgId/maps/groups/:groupId/membersAdds a recipient: an organization member ({ kind: "user", userId }, active at once) or anyone ({ kind: "contact", name?, email?, phone? } with phone in E.164), who is asked to confirm first and stays pending until they do. channels limits what they get.
PATCH /v1/orgs/:orgId/maps/groups/:groupId/members/:memberIdChanges a recipient's name or channels.
POST /v1/orgs/:orgId/maps/groups/:groupId/members/:memberId/resendAsks a pending recipient to confirm again (at most three times, an hour apart).
DELETE /v1/orgs/:orgId/maps/groups/:groupId/members/:memberIdRemoves a recipient.
GET /v1/orgs/:orgId/maps/pushWhere the caller's alerts can go: browsers with web push on, one per browser (subscriptions: subId, app, label, host, createdAt, lastUsedAt; turned on with POST /v1/me/notifications/web-push) and phones that get Maps alerts (phones: deviceId, appId maps, or home on phones without the Maps app, name, model, platform, appVersion, updatedAt).
POST /v1/orgs/:orgId/maps/push/testSends the caller a sample alert on their phones (Maps app) and browsers: mobile (devices, queued) and web (sent, devices).
DELETE /v1/orgs/:orgId/maps/push/subscriptions/:subIdTurns web push off in one of the caller's browsers, for every app there. People only; another person's id changes nothing.
GET /v1/me/maps/locationYour location for near-me alerts: sharing, the phones sharing (devices: deviceId, platform, name, mode foreground or background, retentionHours, enabledAt, lastReportAt), the current fix (current: lat, lon to 3 decimals, accuracyM, at, deviceName, validUntil, or null) and the near-me watches using it (usedBy). From the Maps or mobile apps only.
PUT /v1/me/maps/location/devices/:deviceIdTurns sharing on for this phone or changes it: platform, name, mode (foreground: counts 30 minutes after each report; background: retentionHours 1, 6 or 24 after the last report). A background phone gets its report key (key, si_loc_…) once. Mobile app tokens only, tied to their sign-in.
POST /v1/me/maps/location/devices/:deviceId/reportReports this phone's location: lat, lon, accuracyM, at (ms; at most 10 minutes old), source (foreground, significant, region, open). Stored to 3 decimals, accuracy at least 50 m, one current fix per phone; 204 when dropped (one report per 20 s). Mobile app tokens only.
DELETE /v1/me/maps/location/devices/:deviceIdStops sharing on one phone: its fix and key are deleted.
DELETE /v1/me/maps/locationDeletes your location everywhere: every phone's fix, the phones and their keys. Near-me watches wait until a phone shares again.
GET /v1/me/maps/location/activityYour own log of turning sharing on, background on, stopping, deleting and phones removed at sign-out (action, at, deviceName), kept 90 days. Never coordinates.
GET /v1/me/maps/cars{ cars }: the cars you see, where you may see them (Vehicles' sharing rules), with their state, battery and picture. Empty where Vehicles isn't available.
POST /v1/me/maps/cars/trailsWhere the cars you see have been (docs/maps/timeline.md → Trails): each car's drive so far, or its last drive when it parked recently, as Vehicles shows it to you; null for a car with nothing to show (whatever the reason). Each ask says what you hold, so the answer has only what's new.
GET /v1/me/maps/timelineOne page of what happened between from and to (ISO dates or epoch milliseconds, at most 31 days): { range, items, sources, next?, keeps }. sources (vehicles, flights, people; all by default) picks what is read. next.to asks for the earlier part.
GET /v1/me/maps/layers{ layers: { photos, events, traffic, tasks } }: which of the map's other layers you may turn on here (docs/maps/layers.md): scopes and the org's app switches.
GET /v1/me/maps/layers/photos/:photoIdA photo's card on the map: { photo: { photoId, kind, takenAt, thumbUrl? } }, for one of your own located photos.
GET /v1/me/maps/layers/:layerA layer's things (LayerAnswer): photos (your own, in bbox), events (your events from yesterday to a month ahead, at their places), traffic (your organisation's Cloud traffic by country, the last 7 days) or tasks (your organisation's Tasks issues with a place in bbox, as you can open them in Tasks; spaces (keys) and status (todo, inprogress, done) filter them, open work by default). bbox is west,south,east,north; the answer's box says what it covers (everywhere for events and traffic). state: "off" where it isn't yours to see here.
GET /v1/me/maps/timeline/drives/:vehicleId/:tripIdA drive on the timeline with its track, for playback: as Vehicles' drive detail answers it, for a drive you see.
POST /v1/me/maps/timeline/roadsDrives' lines on the roads they took ({ drives: [{ vehicleId, tripId }] }, up to 50): { roads: { [tripId]: stretches | "pending" | null } }. Display only.
POST /v1/me/maps/directionsDirections (docs/maps/directions.md): { from, to, mode } (drive with live traffic, walk, cycle) answers { routes } (the best and up to two alternatives, with steps; a drive's traffic) or { error: "no_route" | "too_far" | "unavailable" }. POST, so the points stay out of URLs and logs; they go to Mapbox for this request only. Counted per person per hour (maps.directions.routesPerHour): past it, 429 with Retry-After.
GET /v1/me/maps/roads{ on, available }: whether you draw drives on the roads they took (on unless you turned it off), and whether there are drives here.
PUT /v1/me/maps/roadsDraws drives on the roads they took, or as driven ({ on }): your choice, shared with Vehicles' Display.
GET /v1/me/findmy/eta{ mine, shared }: the person's own trips that still run, with who sees them, and the trips shared with them (and offers).
POST /v1/me/findmy/etaStarts sharing a trip: { to: { lat, lon, name? }, mode, durationS, etaAt, remainingM, position?, recipients: [userId] }. 201 { trip, shared }.
GET /v1/me/findmy/eta/:tripIdA trip: { mine } for its sharer, { shared } for someone it's shared with (or an offer to accept), else 404.
POST /v1/me/findmy/eta/:tripId/progressThe sharer's progress: { lat, lon, accuracyM?, etaAt, remainingM }. Near the destination it arrives. { trip }.
POST /v1/me/findmy/eta/:tripId/keyA key for this phone to post the trip's progress while Maps is closed (docs/maps/directions.md → With Maps closed), from a phone's own sign-in only. { key, validUntil }: the key once (it replaces the trip's last), working until the trip ends, the person hides their location or the phone signs out. 409 when the trip has ended or the location is hidden.
POST /v1/me/findmy/eta/:tripId/recipientsShares a running trip with more people: { recipients: [userId] }. { trip, shared }.
DELETE /v1/me/findmy/eta/:tripId/recipients/:userIdStops sharing a trip with one person, at once.
POST /v1/me/findmy/eta/:tripId/extendShares a running trip for longer: { minutes } (5 to 1,440), up to maps.eta.hoursMax after its start. { trip }.
POST /v1/me/findmy/eta/:tripId/linksA link to the trip for someone without an account: 201 { url, link, trip }. The address is answered this once (the token is in its fragment) for the person to send themselves; it ends with the trip, or when they end it.
DELETE /v1/me/findmy/eta/:tripId/links/:linkIdEnds one of the trip's links, at once. { trip }.
DELETE /v1/me/findmy/eta/:tripId/followingStops following someone's trip (the share given back).
DELETE /v1/me/findmy/eta/:tripIdStops sharing a trip with everyone, at once.
GET /v1/me/findmy/people{ me, people }: the person, and everyone they share with, who shares with them, or who asked; where each is, as they may see it.
GET /v1/me/findmy/widget/peopleHome's People widget: { people }, everyone who shares with the person, most recently seen first (10 at most): when, and where in words ("At Mum's", "Near your Work", or their own place names when they show them on an exact share) or how far from lat/lon (where the phone is, optional). No coordinates; each look is a use, as People's.
GET /v1/me/findmy/widget/devicesHome's Devices widget: { phones, cars }, the person's own phones and the cars they see, with battery and when last seen. No positions.
PUT /v1/me/findmy/place-names"Show my place names to people I share with" ({ on }): their own places' names, to exact shares only. Answers me.
GET /v1/me/findmy/suggestions{ people }: Mirage friends, circles and Find My people to share with.
POST /v1/me/findmy/shareShares the person's location: { email | userId, precision?, expiresAt? }. 201 with the Sharing API's result (a grant, pending or not, or an invitation).
PATCH /v1/me/findmy/share/:userIdChanges how you share your location with someone: precision (exact or approximate, about a kilometre) and expiresAt (epoch seconds, or null for none).
DELETE /v1/me/findmy/share/:userIdStops sharing your location with someone. They are told.
PUT /v1/me/findmy/share/:userId/hideHides the person's location from one person until a time (epoch seconds) or forever (until turned back on); they aren't told.
DELETE /v1/me/findmy/share/:userId/hideShows your location to someone again, ending a hide at once.
PUT /v1/me/findmy/hideHides it from everyone: { until } (a time or forever) or { off: true } (Share My Location off). DELETE shows it again.
DELETE /v1/me/findmy/hideShows your location to everyone you share with again: ends a hide or turns Share My Location back on.
DELETE /v1/me/findmy/following/:userIdStops seeing someone's location (gives their share back).
POST /v1/me/findmy/requestsAsks someone to share their location: { email | userId }. Always { sent: true }, account or not. Spends one of the day's shares.
POST /v1/me/findmy/requests/:userId/acceptShares your location with someone who asked (precision optional); they see you at once, with no offer to accept. The request goes.
POST /v1/me/findmy/requests/:userId/declineDeclines someone's request to see your location. They aren't told.
DELETE /v1/me/findmy/requests/out/:userIdWithdraws your own request to see someone's location.
GET /v1/me/findmy/alerts{ alerts }: the person's arrive and leave alerts on people they see.
POST /v1/me/findmy/alertsTells you when someone who shares their location with you arrives at or leaves a place: subjectId, name, lat, lon, radiusM (100 to 50,000; at least 2,000 for an approximate share), on (arrive, leave or both) and repeat. They are told an alert was set. 404 when they don't share with you; at most 20 alerts. 201.
DELETE /v1/me/findmy/alerts/:alertIdRemoves one of your alerts.
GET /v1/me/findmy/devices{ phones, cars }: the person's phones (each signed-in phone and each that reports a location: last location, battery, last seen, their Find My choices; theirs alone), and their Personal cars and the cars shared with them, each where they may see it (Vehicles' privacy), with their own watches on it. Cars come only where Vehicles is on.
POST /v1/me/findmy/devices/phones/:deviceId/soundPlays a sound on one of the person's signed-in phones: one push, there alone (time-sensitive). 202 { sent }.
PATCH /v1/me/findmy/devices/phones/:deviceIdA phone's Find My choices: notifyWhenFound (only while it's offline; its next report tells you, once) and history (off forgets it).
GET /v1/me/findmy/devices/phones/:deviceId/historyThe phone's own fixes, the last day's, oldest first, when you keep its history. Yours alone.
PUT /v1/me/findmy/devices/cars/:vehicleId/left-behindNotify When Left Behind for a car you may see the location of: you're told when it drives off without the phone that shares your location, or that phone leaves it parked away from home. PUT pairs, DELETE unpairs.
DELETE /v1/me/findmy/devices/cars/:vehicleId/left-behindUnpairs a car from Notify When Left Behind.
PUT /v1/me/findmy/devices/cars/:vehicleId/foundNotify When Found for a car you may see the location of, while it's offline: its next position tells you, once.
DELETE /v1/me/findmy/devices/cars/:vehicleId/foundDisarms Notify When Found on a car.