Location events

When a contact shares their location with your line — on iMessage, from Apple's Find My — three event types report it: location.share_started, location.updated with each new position, and location.share_ended. None of them arrives unless you ask for it.

Asking for them

On the stream, open it with ?events=locations. All three types arrive as one frame, event: location, told apart by its type:

curl -N "https://api.mapier.ai/v1/response_stream?events=locations" \
  -H "Authorization: Bearer $MAPIER_API_KEY" \
  -H "x-mapier-version: 2026-10-15" \
  -H "Accept: text/event-stream"

id: 0192a7c4-9b31-7c02-8d44-2f6e1a3b5c70
event: location
data: {"type":"location.updated","conversationId":"a0000000-0000-4000-8000-000000000001","contactId":"c0000000-0000-4000-8000-000000000003","latitude":40.76203,"longitude":-73.985918,"horizontalAccuracyM":12,"capturedAt":"2026-09-30T18:07:00.000Z","occurredAt":"2026-09-30T18:07:00.000Z","simulated":false}

The option combines with the others: ?events=receipts,locations. The frame's fields are in the stream reference.

At a webhook endpoint, subscribe to the types by name on the project's Webhooks page. They are not in the default set: a new endpoint, and Select all, leave them out with the other opt-in types. See Webhooks.

What a share looks like

A share is a start, a run of positions, and an end:

1. location.share_started — the contact started sharing. Its position fields are null when it arrived before the first position.
2. location.updated — a new position, about every 30 seconds per contact sharing. latitude, longitude, horizontalAccuracyM and capturedAt are always set. A position that repeats the last one is framed once.
3. location.share_ended — the contact stopped sharing. Its position fields are null when the end carried no last position.

altitudeM, speedMps and coarseAddress are present only where the device or the platform gave them. Read capturedAt for when the position was taken, not when you received it.

Whose location, and where it is filed

A location belongs to one contact, on their one-to-one conversation with the line — conversationId is that conversation, never a group's, and contactId names the person. It is filed only on a conversation and a contact your project already holds: a person who shares before any message has passed between you is not framed.

To ask someone to share, send them Apple's request card — a message.send with kind: "location_request". See Location.

In test

A location the sandbox phone shares arrives as a location frame with simulated: true.

Related