---
title: Location Sharing | API Docs
description: 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](https://datatracker.ietf.org/doc/html/rfc7946) format: `[longitude, latitude]`.

### 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

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

### 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?

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](#request-a-location))
2. **Read** the locations of everyone sharing with you in a chat, returned as [GeoJSON](https://datatracker.ietf.org/doc/html/rfc7946). ([Read shared locations](#read-shared-locations))

Subscribe to [webhooks](#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

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](/channel/imessage/api/resources/chats/subresources/location/methods/request/index.md).

- [cURL](#tab-panel-0-0)
- [TypeScript](#tab-panel-0-1)
- [Python](#tab-panel-0-2)
- [Go](#tab-panel-0-3)

Terminal window

```
curl -X POST https://api.linqapp.com/api/partner/v3/chats/{chatId}/location/request \
  -H "Authorization: Bearer $LINQ_API_KEY"
```

```
await client.chats.location.request({chatId});
```

```
client.chats.location.request({chat_id})
```

```
client.Chats.Location.Request(context.TODO(), {chatId})
```

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](/channel/imessage/guides/messaging/protocol-selection/index.md). Requesting from someone already sharing with you in that chat also returns `409`, with error code `2015`. See [Error Handling](/channel/imessage/error/index.md) 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](#read-shared-locations) returns an empty `features` array. Subscribe to the [`location.sharing.started` webhook](#webhooks) to know when sharing actually begins.

## 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](/channel/imessage/api/resources/chats/subresources/location/methods/retrieve/index.md).

- [cURL](#tab-panel-1-0)
- [TypeScript](#tab-panel-1-1)
- [Python](#tab-panel-1-2)
- [Go](#tab-panel-1-3)

Terminal window

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

```
await client.chats.location.retrieve({chatId});
```

```
client.chats.location.retrieve({chat_id})
```

```
client.Chats.Location.Retrieve(context.TODO(), {chatId})
```

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

Two event types fire as sharing state changes. Subscribe via the [Webhook Subscriptions API](/channel/imessage/api/resources/webhooks/index.md) and handle them like any other event — see [Webhook Events](/channel/imessage/guides/webhooks/events/index.md) 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](#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.

## Related

- [Location Sharing API reference](/channel/imessage/api/resources/chats/subresources/location/index.md) — request + retrieve endpoints
- [Chats](/channel/imessage/api/resources/chats/index.md) — location requests and reads are scoped to a chat
- [Protocol Selection](/channel/imessage/guides/messaging/protocol-selection#protocol-capabilities/index.md) — location sharing is iMessage-only
- [Webhooks](/channel/imessage/guides/webhooks/index.md) — subscribe to `location.sharing.*` events
- [Error Handling](/channel/imessage/error/index.md) — `409` and other responses