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

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, instead of polling.

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

- [cURL](#tab-panel-48)

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](/guides/messaging/protocol-selection/index.md). See [Error Handling](/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](/api/resources/chats/subresources/location/methods/retrieve/index.md).

- [cURL](#tab-panel-49)

Terminal window

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

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

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](#read-shared-locations) to pull the current coordinates.

## Related

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