Dyme Affiliates

Quickstart

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

1. Search without a key

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.

What destination covers depends on the place:

You pass You get
A city: Paris, Lisbon Hotels across the city, best-rated first. distance_km is null, and sort=distance is refused because a city has no single point to measure from.
A neighborhood: Le Marais, Paris, Shoreditch, London Hotels within about 1 km of the neighborhood's center, best-rated first, each with distance_km. sort=distance works.
lat and lng Hotels within radius_km (5 by default, 1 to 50), nearest first.

A search reads at most 60 hotels, so total is 60 at most, and you see the first limit of them. There's no paging: offset, page or cursor returns a 400. To see different hotels, search a smaller place or add min_stars or min_rating.

2. Read the response

{
  "destination": "Lisbon, Portugal",
  "total": 60,
  "hotels": [
    {
      "id": "lisbon-corpo-santo-lisbon-historical-hotel",
      "name": "Corpo Santo Lisbon Historical Hotel",
      "stars": 5,
      "rating": 9.8,
      "review_count": 2645,
      "address": "Largo do Corpo Santo, 25, Lisbon",
      "latitude": 38.707324,
      "longitude": -9.142008,
      "distance_km": null,
      "photo_url": "https://static.cupid.travel/hotels/238790205.jpg",
      "thumbnail_url": "https://static.cupid.travel/hotels/thumbnail/238790205.jpg",
      "url": "https://travel.dyme.earth/hotels/lisbon-corpo-santo-lisbon-historical-hotel?_from=YOUR_CODE&utm_source=YOUR_CODE&utm_medium=api&utm_campaign=search"
    }
  ]
}
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, full size (often 2,000 px or more and several hundred KB). Use it for a large image. Link to it rather than copying it.
thumbnail_url The same photo, about 400 px wide and around 30 KB. Use it for cards and lists. null when there's no small copy; fall back to photo_url.
distance_km Distance from the point you searched: lat and lng, a place_id, or a neighborhood. null for a city searched by name.
url The hotel's page on Dyme, with your affiliate code on it.

3. Find one hotel by name

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

You get hotel, the best match, and matches, up to four other candidates (an empty list when the name is unambiguous), each in the shape above. city is optional; add it when the name is common.

4. Get one hotel

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

This adds:

Field Meaning
description The hotel's description as plain text, paragraphs separated by a blank line. null when the hotel has none.
description_html The same text as the supplier's HTML. Sanitize it before you put it on a page.
photos, thumbnails Up to five photos, main first, and their small copies in the same order.
amenities The supplier's amenity list, as short strings.
city, country_code City name, and the two-letter ISO country code (FR), or null when unknown.

Every endpoint writes address as street, then city. The supplier's spelling and capitals can differ slightly between search results and this endpoint.

5. Search with a key

A key looks like dyme_live_ followed by 32 characters. Authentication explains how to get one.

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

Response headers:

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.

To check the key is being read, look at any url in the response. It should carry _from= and your code. If it carries utm_source=dyme_api_demo instead, the key wasn't read; see authentication.

6. Caching

Hotel answers carry Cache-Control: private, max-age=86400 with a key (public without). You may store and reuse them for up to 24 hours, so a city page can call the API once a day rather than on every visit.

Next