Skip to content
API Docs
Linq Copy agent prompt
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].

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. Requesting from someone already sharing with you in that chat also returns 409, with error code 2015. 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 always exactly [longitude, latitude] — 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

Every payload carries shared_by (their phone number — or Apple ID email if they shared from the standalone Find My app), shared_with (your number), began_at, and chat_id. On location.sharing.started, ends_at is always present: a timestamp when the share is time-boxed, null when the contact shares indefinitely. On location.sharing.stopped, began_at and ended_at bound the session that just ended — its duration comes from that event alone. 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.

Sharing is per contact, not per chat.

chat_id is the chat the share was first sent to. If that contact’s location becomes visible in another of your chats with them, chat_id stays pinned to the original chat and no second location.sharing.started fires. Stopping likewise fires a single location.sharing.stopped, however many chats the location was visible in.

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