{"openapi":"3.1.0","info":{"title":"Dyme Affiliate API","version":"1.0.0","description":"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.\n\n**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.\n\n**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.\n\n**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":[{"url":"https://affiliates.dyme.earth"},{"url":"https://api.dyme.earth/v1","description":"Earlier address; still served."}],"security":[{"key":[]},{}],"paths":{"/hotels/search":{"get":{"summary":"Hotels in a place","description":"Give exactly one of `destination`, `place_id`, or `lat` + `lng`. Returns cards, best-rated first (nearest first for a point).","parameters":[{"name":"destination","in":"query","schema":{"type":"string"},"description":"A place name: \"Shoreditch, London\", \"Lisbon\", \"Bali\"."},{"name":"place_id","in":"query","schema":{"type":"string"},"description":"A Google Place ID, from your own Google Places box."},{"name":"lat","in":"query","schema":{"type":"number"}},{"name":"lng","in":"query","schema":{"type":"number"}},{"name":"radius_km","in":"query","schema":{"type":"number","minimum":1,"maximum":50,"default":5},"description":"Around a lat + lng point only."},{"name":"label","in":"query","schema":{"type":"string"},"description":"Echoed as `destination` for a lat/lng or place_id search."},{"name":"limit","in":"query","schema":{"type":"integer","default":10,"minimum":1,"maximum":20}},{"name":"sort","in":"query","schema":{"type":"string","enum":["rating","stars","distance"]},"description":"Default `rating`; `distance` needs a point."},{"name":"min_stars","in":"query","schema":{"type":"number","minimum":1,"maximum":5}},{"name":"min_rating","in":"query","schema":{"type":"number","minimum":0,"maximum":10},"description":"Guest score out of 10."},{"name":"sub_id","in":"query","schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,200}$"},"description":"Your own tag for this placement. Returned links carry it as `utm_content`."}],"responses":{"200":{"description":"Hotels","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/hotels/find":{"get":{"summary":"One hotel by name","description":"The link for a hotel you already have in mind: \"St Regis San Francisco\". Returns the best match and up to five candidates.","parameters":[{"name":"name","in":"query","required":true,"schema":{"type":"string"},"description":"The hotel's name as people say it."},{"name":"city","in":"query","schema":{"type":"string"},"description":"Helps when the name is common: \"Hilton\" needs a city."},{"name":"sub_id","in":"query","schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,200}$"},"description":"Your own tag for this placement. Returned links carry it as `utm_content`."}],"responses":{"200":{"description":"Best match and candidates","content":{"application/json":{"schema":{"type":"object","properties":{"hotel":{"$ref":"#/components/schemas/HotelCard"},"matches":{"type":"array","items":{"$ref":"#/components/schemas/HotelCard"}}}}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/hotels/{id}":{"get":{"summary":"One hotel: description, photos, amenities","description":"Everything for a post about one hotel. Up to five photos, main first.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"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."},{"name":"sub_id","in":"query","schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,200}$"},"description":"Your own tag for this placement. Returned links carry it as `utm_content`."}],"responses":{"200":{"description":"Hotel","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Hotel"}}}},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/links":{"post":{"summary":"Make any Dyme URL credit your key","description":"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.","parameters":[{"name":"sub_id","in":"query","schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{1,200}$"},"description":"Your own tag for this placement. Returned links carry it as `utm_content`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["urls"],"properties":{"urls":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":10}}}}}},"responses":{"200":{"description":"Links, in order. `url` is null with an `error` when a URL is not Dyme's or already carries another partner's code."},"400":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}}},"components":{"securitySchemes":{"key":{"type":"http","scheme":"bearer","description":"Authorization: Bearer dyme_live_…"}},"responses":{"Error":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthorized","rate_limited","invalid_params","not_found","upstream_unavailable"]},"message":{"type":"string"}}}}}}}}},"schemas":{"HotelCard":{"type":"object","properties":{"id":{"type":"string","description":"Dyme hotel id: the hotel's page path. Use it with /hotels/{id}."},"name":{"type":"string"},"stars":{"type":["number","null"]},"rating":{"type":["number","null"],"description":"Guest score out of 10"},"review_count":{"type":["integer","null"]},"address":{"type":"string"},"latitude":{"type":["number","null"]},"longitude":{"type":["number","null"]},"distance_km":{"type":["number","null"],"description":"From the searched point, when there was one"},"photo_url":{"type":["string","null"],"description":"Main photo. Link to it; never copy it."},"url":{"type":"string","description":"The hotel's page on Dyme, credited to you"}}},"SearchResponse":{"type":"object","properties":{"destination":{"type":"string","description":"The place as we understood it"},"total":{"type":"integer","description":"Hotels matching before `limit`"},"hotels":{"type":"array","items":{"$ref":"#/components/schemas/HotelCard"}}}},"Hotel":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"stars":{"type":["number","null"]},"rating":{"type":["number","null"]},"review_count":{"type":["integer","null"]},"address":{"type":"string"},"city":{"type":"string"},"country_code":{"type":"string"},"latitude":{"type":"number"},"longitude":{"type":"number"},"description":{"type":"string"},"photo_url":{"type":["string","null"]},"photos":{"type":"array","items":{"type":"string"},"description":"Up to five, main first"},"amenities":{"type":"array","items":{"type":"string"}},"url":{"type":"string"}}}}}}