# Quickstart

Your first search, and the same search with a key.

HTML version: https://dyme.earth/affiliates/build/quickstart

## 1. Search without a key

```bash
curl "https://affiliates.dyme.earth/hotels/search?destination=Lisbon&limit=3"
```

Pass one of `destination`, `place_id`, or `lat` and `lng`. `limit` is 10 by default and 20 at most. `sort` can be `rating` (the default), `stars` or `distance`, and `min_stars` and `min_rating` narrow the list. Without a key you get 30 requests an hour per IP address. There's no sandbox to switch to: keyless calls return the real data.

## 2. Read the response

```json
{
  "destination": "Lisbon",
  "total": 412,
  "hotels": [
    {
      "id": "lisbon-pestana-rua-augusta-lisboa",
      "name": "Pestana Rua Augusta Lisboa",
      "stars": 4,
      "rating": 9.7,
      "review_count": 541,
      "address": "Rua Augusta 200, 1100-053 Lisboa, Portugal",
      "latitude": 38.7107,
      "longitude": -9.1376,
      "distance_km": null,
      "photo_url": "https://static.cupid.travel/hotels/498652396.jpg",
      "url": "https://travel.dyme.earth/hotels/lisbon-pestana-rua-augusta-lisboa?_from=YOUR_CODE&utm_source=YOUR_CODE&utm_medium=api"
    }
  ]
}
```

| Field | Meaning |
|---|---|
| `id` | The hotel's ID on Dyme. It's also the last part of its page address, `https://travel.dyme.earth/hotels/{id}`, and what you pass to `/hotels/{id}`. |
| `stars` | Star rating, 1 to 5, or `null` if the hotel doesn't have one. |
| `rating`, `review_count` | Guest score out of 10, and how many reviews it's based on. |
| `photo_url` | The main photo. Link to it rather than copying it. |
| `distance_km` | Distance from the point you searched, when you searched by `lat` and `lng`. |
| `url` | The hotel's page on Dyme, with your affiliate code on it. |

## 3. Find one hotel by name

```bash
curl "https://affiliates.dyme.earth/hotels/find?name=St%20Regis&city=San%20Francisco"
```

You get `hotel`, the best match, and `matches`, up to five other candidates, each in the shape above. `city` is optional; add it when the name is common.

## 4. Get one hotel

```bash
curl "https://affiliates.dyme.earth/hotels/lisbon-pestana-rua-augusta-lisboa"
```

This adds `description`, `photos` (up to five, main first), `amenities`, `city` and `country_code`.

## 5. Search with a key

A key looks like `dyme_live_` followed by 32 characters. [Authentication](https://dyme.earth/affiliates/build/authentication) explains how to get one.

```bash
curl "https://affiliates.dyme.earth/hotels/search?destination=Lisbon" \
  -H "Authorization: Bearer dyme_live_YOUR_KEY"
```

Response headers:

```http
X-RateLimit-Limit: 2000
X-RateLimit-Remaining: 1998
X-RateLimit-Reset: 1790146800
```

With a key, every `url` carries your affiliate code, so bookings that start from them are credited to you.

## Next

- [Authentication](https://dyme.earth/affiliates/build/authentication)
- [Rate limits](https://dyme.earth/affiliates/build/limits)
- [Attribution](https://dyme.earth/affiliates/build/attribution)
- [API reference](https://dyme.earth/affiliates/build/reference)