API Overview

ScrapeGuys exposes real-time travel pricing through a small set of REST endpoints. This page covers the concepts shared by every scraper — authentication, base URLs, the async job workflow, rate limits and errors. Each scraper then has its own reference page.

Base URLs

The scrapers are served by two independent API surfaces. Each has its own API keys (see Authentication).

Authentication

Every request must include your API key in the X-API-Key header. Keys are 68-character strings; the Hotel API issues gsk_… keys and the Flight API issues fsk_… keys. The two are independent — a Hotel key does not authenticate the Flight API and vice-versa.

Scopes. Both key types carry an explicit scope list controlling which sources they may call. A gsk_… key can hold: gmaps (Google Hotels), ota:agoda (Agoda), ota:booking (Booking.com), ota:makemytrip (MakeMyTrip), ota:expedia (Expedia), ota:goibibo (Goibibo), and destination:booking (Destination Search). A fsk_… key can hold: google_flights (Google Flights) and/or makemytrip (MakeMyTrip Flights, both its app and desktop platforms), per source. Which of these a given key actually carries depends on when it was issued and what was requested for it — see below. Calling an endpoint or source outside your key's scopes returns 403 with {"detail": "This API key does not have the '<scope>' scope."}. There is no wildcard scope — a source added later is never automatically granted to existing keys.

X-API-Key: gsk_a1b2c3d4e5f6...   # Hotel API (Google Hotels + OTA rates)
X-API-Key: fsk_a1b2c3d4e5f6...   # Flight API (Google Flights)

• 401 Unauthorized — missing, invalid, or deactivated key.
• 403 Forbidden — key is valid but lacks the required scope.

Request a free developer trial to get your keys.

The job workflow

Every scraping endpoint is asynchronous. You submit a job, receive a job_id and a poll_url, then poll until the job reaches a terminal state:

1. Submit — POST …/scrape/ (or POST …/ota-price/) returns 202 with { job_id, status: "pending", poll_url }.
2. Poll — GET the poll_url every ~2 seconds. status moves pending → processing → completed (or failed).
3. Read — when status is completed, the result object holds the data.

Rate limits & quotas

Limits are enforced per API client and are configurable per plan. Defaults:

"Per billing cycle" is not always the calendar month: each client has a billing_cycle_day (1–28) the monthly quota resets on. New clients are anchored to their sign-up day; clients provisioned before billing cycles existed run on day 1 — the calendar month, unchanged. GET /usage/'s billing_period block reports your account's actual window.

Exceeding any limit returns HTTP 429 with a descriptive detail, e.g. "Rate limit exceeded (10/min). Try again shortly."

Errors

Usage endpoint

Check your consumption against your quotas at any time. Available on both surfaces:

# Hotel API (Google Hotels + OTA rates)
curl "https://gumo.co.in/api/v1/scraper/usage/?days=30" \
  -H "X-API-Key: gsk_your_api_key"

# Flight API (Google Flights)
curl "https://gumo.co.in/api/v1/flight-scraper/usage/?days=30" \
  -H "X-API-Key: fsk_your_api_key"

{
  "client": "Your Company Name",
  "billing_period": { "cycle_day": 1, "start": "2026-04-01", "end": "2026-04-30", "resets_on": "2026-05-01" },
  "lifetime": { "total_requests": 12450, "total_bandwidth_kb": 3245678.5 },
  "limits": { "rate_limit_per_minute": 10, "daily_quota": 1000, "monthly_quota": 20000 },
  "usage": [
    { "date": "2026-04-08", "request_count": 142, "success_count": 138,
      "failure_count": 4, "total_duration_seconds": 856.3, "total_bandwidth_kb": 36890.2 }
  ]
}

days is clamped into the 1–90 range (out-of-range values are adjusted, not rejected); a non-integer returns 400 (days must be an integer (1–90))

billing_period is the window "monthly" means for your account — the monthly quota is summed over your billing cycle, which starts on cycle_day of each month and resets on resets_on, the date your monthly quota springs back to the full amount. start and end are both inclusive. Identical shape on both APIs, so a customer of both reads one contract.

Client dashboard

A browser dashboard of your own scraping activity — submitted / succeeded / failed / in-flight counts as KPI cards, a time-series chart, and a PDF export. Sign in with the portal username/email + password you were provisioned (ask your Gumo contact), or with any of your active Hotel or Flight API keys. Either way the dashboard is scoped server-side to your data only, and access ends the moment your credentials are revoked on our side.

For programmatic access, the same stats are available as JSON or PDF using just your API key — no sign-in needed:

curl "https://gumo.co.in/client/scrape-dashboard/data/?range=7d" \
  -H "X-API-Key: gsk_your_api_key"   # or an fsk_ key

With nothing supplied the window defaults to the last 7 days. Unrecognized values are ignored (not rejected) and reported back in a warnings array; the request still succeeds with the default window applied.

{
  "series": [
    { "bucket": "2026-08-06T00:00:00+05:30", "label": "2026-08-06 00:00",
      "submitted": 42, "succeeded": 39, "failed": 2, "in_flight": 1 }
  ],
  "per_client": [
    { "client_id": 123, "client_name": "Your Company Name",
      "submitted": 312, "succeeded": 298, "failed": 14,
      "in_flight": 0, "success_rate": 95.5 }
  ],
  "totals": { "submitted": 312, "succeeded": 298, "failed": 14, "in_flight": 0, "success_rate": 95.5 },
  "meta": { "granularity": "hour", "start": "2026-08-06T00:00:00+05:30",
    "end": "2026-08-13T00:00:00+05:30", "client_id": 123, "range_key": "7d" }
}

per_client contains at most one row — your own — the dashboard endpoints never return another client's name, id or volume. bucket timestamps are UTC-offset ISO 8601; label is the same instant formatted for display in Asia/Kolkata.

/client/scrape-dashboard/pdf/ takes the same query params and streams a PDF (Content-Type: application/pdf) instead of JSON.

Ready to dive in? Pick a guide: Google Flights · MakeMyTrip Flights · Google Hotels · Agoda · Booking.com · MakeMyTrip Hotels · Expedia · Goibibo · Destination Search · Rate Shop.