Location Sharing
Request a chat participant's location and read incoming location updates as GeoJSON.
Request and retrieve real-time location data via iMessage.
Use these endpoints to request a contact’s location, retrieve location data for contacts who are sharing with you, and subscribe to webhooks when someone starts or stops sharing their location.
Coordinates are returned in GeoJSON format:
[longitude, latitude] or [longitude, latitude, altitude] if altitude is available.
Location sharing is a two-part flow:
- Request a participant’s location — they get a prompt asking them to share. (Request a location)
- Read the locations of everyone sharing with you in a chat, returned as GeoJSON. (Read shared locations)
Subscribe to webhooks to be notified the moment someone starts or stops sharing, instead of polling.
Request a location
Section titled “Request a location”Send a location request to the other participant in a chat: POST /v3/chats/{chatId}/location/request. They receive a prompt asking them to share their current location. See the Request Location API reference.
curl -X POST https://api.linqapp.com/api/partner/v3/chats/{chatId}/location/request \ -H "Authorization: Bearer $LINQ_API_KEY"Requesting a location only works in 1:1 iMessage chats. Requesting in a group chat, or in an SMS or RCS chat, returns HTTP 409 — the operation isn’t supported on that chat’s service type. See Error Handling for response details.
A request only prompts the recipient — they choose whether to share, and for how long. Until they accept, reading locations returns an empty features array. Subscribe to the location.sharing.started webhook to know when sharing actually begins.
Read shared locations
Section titled “Read shared locations”Retrieve the current location of everyone sharing with you in a chat: GET /v3/chats/{chatId}/location. See the Get Location API reference.
curl https://api.linqapp.com/api/partner/v3/chats/{chatId}/location \ -H "Authorization: Bearer $LINQ_API_KEY"The response is a GeoJSON FeatureCollection with one Feature per participant actively sharing. Works for both 1:1 and group chats — in a group, each sharing participant is a separate feature, identified by properties.handle. If no one is sharing yet, features is an empty array.
Each feature’s geometry.coordinates are [longitude, latitude], or [longitude, latitude, altitude] when altitude is available — note the longitude-first ordering per the GeoJSON spec. Feature properties include:
| Field | Description |
|---|---|
handle | Phone number or email of the person sharing |
address | Full street address (when available) |
locality | City or locality name (when available) |
updated_at | When the location was last updated |
Webhooks
Section titled “Webhooks”Two event types fire as sharing state changes. Subscribe via the Webhook Subscriptions API and handle them like any other event — see Webhook Events for the envelope and delivery guarantees.
| Event | Fires when |
|---|---|
location.sharing.started | A participant starts sharing their location with you |
location.sharing.stopped | A participant stops sharing |
Both payloads carry shared_by (their number) and shared_with (your number); location.sharing.started also includes began_at and, when sharing is time-boxed, ends_at. After a started event, call Read shared locations to pull the current coordinates.
Related
Section titled “Related”- Location Sharing API reference — request + retrieve endpoints
- Chats — location requests and reads are scoped to a chat
- Protocol Selection — why location requests require iMessage
- Webhooks — subscribe to
location.sharing.*events - Error Handling —
409and other responses