Rate Shop

Price many hotels, on many OTAs, across every arrival date in a range — in one request. This is the axis per-hotel OTA pricing can't express: that endpoint prices exactly one hotel, on one OTA, for one stay, so a 30-day three-OTA shop of ten hotels would be 900 separate calls to build and 900 URLs to poll.

Base URL: https://gumo.co.in · Auth: X-API-Key: gsk_… with the ota:<slug> scope for every OTA named in the shop · See the Overview.

Submit a job

curl -X POST https://gumo.co.in/api/v1/scraper/rate-shop/ \
  -H "X-API-Key: gsk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "hotels": [
      {"place_id": "ChIJm14which9bDkRXF7ciSSR4eA"},
      {"hotel_name": "The Leela Palace", "city": "Bengaluru"}
    ],
    "otas": ["agoda", "booking", "makemytrip"],
    "start_date": "2026-10-01",
    "end_date":   "2026-10-30",
    "los": 1,
    "adults": 2,
    "rooms": 1,
    "currency": "INR",
    "device_type": "desktop"
  }'

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "cells": 180, "hotels": 2, "otas": 3, "dates": 30,
  "poll_url": "/api/v1/scraper/rate-shop/550e8400-e29b-41d4-a716-446655440000/"
}

Identifying each hotel

A hotel is named by place_id (recommended — one key that works across all three OTAs) or by hotel_name + city.

Whatever identity you send is echoed back on every cell it produces, and it must be unique within the request — two entries resolving to one identity are rejected naming both positions, because their cells would be indistinguishable and you would silently attribute one hotel's prices to both.

On the three OTAs whose own id fully addresses a property (Agoda, Booking.com, MakeMyTrip), a place_id is bridged to that OTA's own id on the first cell that resolves it, and then pinned — every later cell inherits it, which is what makes origin_hotel_name worth checking on the summary row rather than only in each full matrix (see Response schema below).

What a rate shop costs

The whole shop is priced before any work starts and refused as a unit if it will not fit your remaining daily or monthly quota — with the arithmetic in the message:

{
  "detail": "This request needs 180 of your daily quota but only 44 remain (1000/day). Split it by date range or by hotel."
}

That is deliberate. The alternative is to start the fan-out and fail partway, which bills you for a matrix you cannot use and leaves you unable to tell which half ran. Nothing is created on a refusal. The per-minute rate limit applies to the submit only — the fan-out is ours, not yours.

See Rate limits & quotas on the Overview page for how GET /usage/'s in_flight block reports work already accepted but not yet billed — including cells of a rate shop still running.

Poll for results

curl https://gumo.co.in/api/v1/scraper/rate-shop/YOUR_JOB_ID/ \
  -H "X-API-Key: gsk_your_api_key"
# Optionally: ?include=result — see below

Response schema

{
  "id": "550e8400-...", "status": "processing",
  "complete": "57/180", "cell_count": 180,
  "hotels": [{"place_id": "ChIJ…"}, {"hotel_name": "The Leela Palace", "city": "Bengaluru"}],
  "otas": ["agoda", "booking", "makemytrip"],
  "start_date": "2026-10-01", "end_date": "2026-10-30", "los": 1,
  "adults": 2, "rooms": 1, "currency": "INR", "device_type": "desktop",
  "account_labels": {}, "results_embedded": false,
  "results": [
    {
      "job_id": "9c1f…",
      "place_id": "ChIJm14which9bDkRXF7ciSSR4eA", "hotel_name": "", "city": "",
      "ota": "agoda", "check_in": "2026-10-01", "check_out": "2026-10-02",
      "status": "completed", "error_message": "",
      "cheapest_fitting_price": 22500.0, "cheapest_fitting_basis": "per_night_before_taxes",
      "sold_out": false, "hotel_id": "16082488",
      "origin_hotel_name": "The Taj Mahal Palace, Mumbai",
      "account_label": "",
      "poll_url": "/api/v1/scraper/ota-price/9c1f…/"
    }
  ],
  "error_message": "", "created_at": "2026-09-01T12:00:00Z", "completed_at": null
}

Rows are summaries; full matrices are one fetch away

The poll does not embed each cell's room matrix, and could not — one Agoda cell measures 217 KB (11 room types, 85 offers), so a 1,000-cell shop would be a ~212 MB response. Each row instead carries the figures a rate shop is built on:

Each row echoes the identity the hotel was submitted under, so (place_id, ota, check_in) — or (hotel_name, city, ota, check_in) for name-identified hotels — addresses exactly one cell and is the key to join the matrix onto your own catalogue.

Errors — on submit: 400 (validation, a hotel with no identity, duplicate hotels, an unsupported currency for one of the OTAs, children, a disabled OTA, own_account / account_credential, or an account not available on every OTA named), 403 (the key lacks ota:<slug> for any OTA named — the whole shop is refused), 429 (per-minute limit, or the shop exceeds remaining daily or monthly quota), 503 (signed-in pricing is provisioned but momentarily unreadable on our side — retry). On poll: 404 (unknown id, or another client's — its existence is not disclosed), 403 (the key no longer holds the scope for an OTA in the shop).

Signed-in pricing in a shop

signed_in, account_type and account work as they do on the per-hotel endpoints — but a credential is per-(OTA, account), so a shop resolves one account per OTA and the response reports them as a map:

{ "account_labels": { "agoda": "corporate", "booking": "7:corporate", "makemytrip": "corporate" } }

Each cell is priced as its own OTA's account, and account_label on each result row says which. A single label would have been wrong rather than merely limited: the same name usually does not exist on all three, so a three-OTA shop would have priced two of them anonymously while reporting an account.

If you name an account explicitly it must be valid on every OTA in the request — a shop that cannot be signed in everywhere it was asked to is refused whole at submit, rather than pricing part of the matrix anonymously under an account's name.

Next: Destination Search →