Skip to content
API Docs
Get started
Location Sharing
Overview

Location Sharing

Request a chat participant's location and read incoming location updates as GeoJSON.

Request a contact’s location, retrieve location for contacts sharing with you, and subscribe to webhooks when someone starts or stops sharing.

Coordinates are returned in GeoJSON format: [longitude, latitude] or [longitude, latitude, altitude] if altitude is available.

Reading location is poll-based

Section titled “Reading location is poll-based”

Poll GET /v3/chats/{chatId}/location whenever you need the latest position. There is no webhook that pushes updated coordinates — the location.sharing.started / location.sharing.stopped webhooks fire only when a contact begins or ends sharing, not on each position update. To track a moving contact, poll the GET endpoint.

Freshness

Section titled “Freshness”

Each feature’s properties.updated_at tells you when that participant’s location was last updated — use it to judge freshness.

Polling guidance

Section titled “Polling guidance”

Locations refresh on Apple’s cadence, not per request — polling faster than a participant’s location actually updates just returns the same position. Poll at a modest interval (for example, once every few minutes per chat) rather than continuously.

Why is location empty after location.sharing.started fired?

Section titled “Why is location empty after location.sharing.started fired?”

If the contact started sharing from the standalone Find My app instead of the Messages conversation, the share may be tied to their Apple ID email rather than their phone number — the webhook’s shared_by field shows the email in that case. Location is readable only through a chat with the handle that shared, so GET /v3/chats/{chatId}/location on the phone-number chat stays empty.

The fix: have the contact stop sharing and re-share from Find My inside the Messages conversation with your number.

Location sharing is a two-part flow:

  1. Request a participant’s location — they get a prompt asking them to share. (Request a location)
  2. 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. The coordinates themselves are poll-based — there is no webhook for location updates, so read the endpoint whenever you need the latest position.

Request a location

Section titled “Request a location”

Request the other participant in a chat to share their location: POST /v3/chats/{chatId}/location/request. They receive an iMessage prompt and must accept before any location is available. The request is delivered asynchronously — the endpoint returns immediately and does not return coordinates. See the Request Location API reference.

Terminal window
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.

Requesting is not the same as receiving.

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.

Terminal window
curl https://api.linqapp.com/api/partner/v3/chats/{chatId}/location \
  -H "Authorization: Bearer $LINQ_API_KEY"

The response is wrapped in the standard { "success": true, "data": ... } envelope — the body is not a bare GeoJSON document. data 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, data.features is an empty array.

To track a moving contact, poll this endpoint — locations refresh on Apple’s cadence, not per request, so poll at a modest interval (for example, once every few minutes per chat); faster polling just returns the same position. properties.updated_at tells you when each participant’s location was last updated.

Sharing started, but features stays empty?

If the contact started sharing from the standalone Find My app instead of the Messages conversation, the share may be tied to their Apple ID email rather than their phone number (the webhook’s shared_by shows the email in that case). Location is readable only through a chat with the handle that shared. The fix: have the contact stop sharing and re-share from Find My inside the Messages conversation with your number.

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:

FieldDescription
handlePhone number or email of the person sharing
addressFull street address (when available)
localityCity or locality name (when available)
updated_atWhen 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.

EventFires when
location.sharing.startedA participant starts sharing their location with you
location.sharing.stoppedA participant stops sharing

Both payloads carry shared_by (their phone number — or Apple ID email if they shared from the standalone Find My app) 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. These events fire only when sharing begins or ends — there is no webhook for coordinate updates.

Section titled “Related”
© 2026 Linq, Inc. · linqapp.com