# Dyme Affiliate API 1.0.0: API reference

Generated from https://affiliates.dyme.earth/openapi.json. The HTML version is at https://dyme.earth/affiliates/build/reference.

Show Dyme hotels on your site or in your agent. Every `url` carries your affiliate code: hotel bookings within 90 days of the click (last click) earn up to 5%. The traveller books on Dyme.

**What you get.** A hotel is a name, star rating, guest score, photos, its place, and a link. Prices, rooms and reviews are on the hotel page, which is where your link goes. Nothing here needs dates.

**Access.** Without a key: 30 requests an hour per IP address, including from a browser. With a key (apply at https://dyme.earth/affiliates; approved affiliates can ask for one): 2,000 requests a day. `/links` counts one request per URL; Every response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`; a 429 carries `Retry-After`. There is no sandbox: the keyless tier is the sandbox.

**Display rules.** Link to hotel photos; never copy or re-host them. Search when a person asks. Credit Dyme ("Book on Dyme", linked) wherever our hotels appear.

## Servers

- `https://affiliates.dyme.earth`
- `https://api.dyme.earth/v1`: Earlier address; still served.

## Authentication

Optional. `Authorization: Bearer dyme_live_…` raises your request limit and puts your code on the links. Without it, 25 points an hour per IP address (a dozen searches).

## Endpoints

### GET /hotels/search

Hotels in a place

Give exactly one of `destination`, `place_id`, or `lat` + `lng`. Returns cards, best-rated first (nearest first for a point).

| Parameter | In | Required | Description |
|---|---|---|---|
| `destination` | query | no | A place name: "Shoreditch, London", "Lisbon", "Bali". (string) |
| `place_id` | query | no | A Google Place ID, from your own Google Places box. (string) |
| `lat` | query | no | (number) |
| `lng` | query | no | (number) |
| `radius_km` | query | no | Around a lat + lng point only. (number) |
| `label` | query | no | Echoed as `destination` for a lat/lng or place_id search. (string) |
| `limit` | query | no | (integer) |
| `sort` | query | no | Default `rating`; `distance` needs a point. (`rating`, `stars`, `distance`) |
| `min_stars` | query | no | (number) |
| `min_rating` | query | no | Guest score out of 10. (number) |
| `sub_id` | query | no | Your own tag for this placement. Returned links carry it as `utm_content`. (string) |

### GET /hotels/find

One hotel by name

The link for a hotel you already have in mind: "St Regis San Francisco". Returns the best match and up to five candidates.

| Parameter | In | Required | Description |
|---|---|---|---|
| `name` | query | yes | The hotel's name as people say it. (string) |
| `city` | query | no | Helps when the name is common: "Hilton" needs a city. (string) |
| `sub_id` | query | no | Your own tag for this placement. Returned links carry it as `utm_content`. (string) |

### GET /hotels/{id}

One hotel: description, photos, amenities

Everything for a post about one hotel. Up to five photos, main first.

| Parameter | In | Required | Description |
|---|---|---|---|
| `id` | path | yes | The hotel `id` from a search or find result, e.g. `london-the-hoxton-shoreditch`. It is also the hotel's page path on Dyme. (string) |
| `sub_id` | query | no | Your own tag for this placement. Returned links carry it as `utm_content`. (string) |

### POST /links

Make any Dyme URL credit your key

Paste any dyme.earth or travel.dyme.earth address — a hotel page, a search, the home page — and get it back with your affiliate code on it. Counts one request per URL.

| Parameter | In | Required | Description |
|---|---|---|---|
| `sub_id` | query | no | Your own tag for this placement. Returned links carry it as `utm_content`. (string) |

Request body (JSON):

```json
{
  "type": "object",
  "required": [
    "urls"
  ],
  "properties": {
    "urls": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "minItems": 1,
      "maxItems": 10
    }
  }
}
```

## Try it

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