> ## Documentation Index
> Fetch the complete documentation index at: https://docs.staging.relayapp.im/llms.txt
> Use this file to discover all available pages before exploring further.

# Places

> Send a place to a person, and read the places people send your agent.

A place is one point on the map, sent once, with an optional name and address. Your agent sends a place to show where something is, and a person sends one to show where they are or where they dropped a pin.

A place does not move. To follow a person while they move, use [location sharing](https://docs.staging.relayapp.im/chats/location.md).

## Send a place

Add a `place` part to the message. It can be the only part, or sit beside text:

**Preview**

An agent's place as the person sees it; tap the card

**JSON**

```json theme={null}
{
  "message": {
    "parts": [
      {"type":"text","value":"Here is the coffee shop."},
      {
        "type": "place",
        "latitude": 37.44216251868683,
        "longitude": -122.16153582049394,
        "name": "Philz Coffee",
        "address": "101 Forest Ave, Palo Alto, CA 94301"
      }
    ]
  }
}
```

| Field | Rule |
| - | - |
| `latitude` | Required number from -90 to 90, in degrees (WGS 84) |
| `longitude` | Required number from -180 to 180, in degrees (WGS 84) |
| `name` | Optional. 1 to 256 characters after Relay trims it |
| `address` | Optional. 1 to 256 characters after Relay trims it |

The app draws the place as a map card with the name, the address, and **Maps**. With no name, the card says **Dropped Pin**. A tap opens Apple Maps at the point.

Send the body to `POST /v1/chats/{chatId}/messages` ([reference](https://docs.staging.relayapp.im/api-reference/messages/send-a-message-to-an-existing-chat.md)). The SDK method is `relay.chats.messages.send`:

```bash cURL theme={null}
curl -sS -X POST "https://api.staging.relayapp.im/v1/chats/$CHAT_ID/messages" \
  -H "Authorization: Bearer $RELAY_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: place-philz-1" \
  -d '{
    "message": {
      "parts": [
        {"type": "text", "value": "Here is the coffee shop."},
        {"type": "place", "latitude": 37.44216251868683, "longitude": -122.16153582049394, "name": "Philz Coffee", "address": "101 Forest Ave, Palo Alto, CA 94301"}
      ]
    }
  }'
```

```typescript TypeScript theme={null}
import Relay from "@relaymessenger/sdk";

const relay = new Relay({
  apiKey: process.env.RELAY_AGENT_TOKEN!,
  baseURL: "https://api.staging.relayapp.im",
});

const sent = await relay.chats.messages.send(process.env.CHAT_ID!, {
  message: {
    parts: [
      { type: "text", value: "Here is the coffee shop." },
      {
        type: "place",
        latitude: 37.44216251868683,
        longitude: -122.16153582049394,
        name: "Philz Coffee",
        address: "101 Forest Ave, Palo Alto, CA 94301",
      },
    ],
    idempotency_key: "place-philz-1",
  },
});
console.log(sent.message.id);
```

Reuse the same `Idempotency-Key` and body after an uncertain send.

## Receive a place

A person sends a place from the app in two ways:

* **Once**, in the **Share My Location** menu of your agent's [location request](https://docs.staging.relayapp.im/chats/location.md), sends where the person is now. No share starts.
* **Location** in the **+** menu of a one-to-one chat with your agent opens a map. The person drops a pin and taps **Send Pin**.

Both arrive as [`message.received`](https://docs.staging.relayapp.im/events/message-received) with a `place` part. The app adds the address the phone finds for the point, and no name:

**Preview**

A person's dropped pin on their own screen; tap the card

**JSON**

```json theme={null}
{
  "type": "place",
  "latitude": 37.44692,
  "longitude": -122.16126,
  "address": "461 Florence St, Palo Alto, CA  94301",
  "reactions": null
}
```

The address is Apple's own for the point, as the phone received it. It is absent when the phone finds none, so read `name` and `address` only when they are present.

## What you get back

Relay answers `202` with the stored message. Its `place` part comes back as you sent it, with `reactions`:

```json theme={null}
{
  "type": "place",
  "latitude": 37.44216251868683,
  "longitude": -122.16153582049394,
  "name": "Philz Coffee",
  "address": "101 Forest Ave, Palo Alto, CA 94301",
  "reactions": null
}
```

A reader that does not draw places, and the push notification, show the place's name, else its address, else `Dropped Pin`. Beside text, those words go on their own line.

## When it fails

| Status | Code | Cause | Next action |
| - | - | - | - |
| `400` | [`1005`](https://docs.staging.relayapp.im/error/codes/1xxx/1005) | `latitude` or `longitude` is missing or out of range, `name` or `address` is empty after trimming or over 256 characters, or the part has another field. | Correct the part. |

## Next steps

* [Share a live location](https://docs.staging.relayapp.im/chats/location.md)
* [Read the message parts](https://docs.staging.relayapp.im/messages/parts.md)
* [Receive the message.received event](https://docs.staging.relayapp.im/events/message-received.md)
* [Send a message](https://docs.staging.relayapp.im/messages/send.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.