API Reference

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.

🏨

Google Hotels

Multi-OTA price comparison + rich hotel metadata. Async jobs.

✈️

Google Flights

Structured priced flight offers with per-segment detail. Async jobs.

💰

Hotel Rates (OTA)

Direct per-room rates from Agoda, Booking.com & MMT. Async jobs.

Base URLs

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

Surface	Base URL	Covers
Hotel API	`https://gumo.co.in/api/v1/scraper`	Google Hotels + Hotel Rates (OTA direct)
Flight API	`https://gumo.co.in/api/v1/flight-scraper`	Google Flights

Note: replace gumo.co.in with the host provided to you during onboarding if it differs. All examples on these docs use the host above.

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 (Hotel API). Each gsk_… key carries an explicit scope list controlling which scrapers it may call: gmaps (Google Hotels) and ota:agoda, ota:booking, ota:makemytrip (Hotel Rates, per OTA). Calling an endpoint outside your key's scopes returns 403 with {"detail": "This API key does not have the '<scope>' scope."}. Flight keys have no scopes.

Authorization header

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

All three scrapers are asynchronous. You submit a job, receive a job_id and a poll_url, then poll until the job reaches a terminal state:

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

Jobs poll on their own surface: Google Hotels jobs at /scrape/{job_id}/, Hotel Rates jobs at /ota-price/{job_id}/, Google Flights jobs at /flight-scraper/scrape/{job_id}/. Polling a job on the wrong endpoint returns 404.

Rate limits & quotas

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

Limit	Default	Window
Rate limit	10 requests	per minute
Daily quota	1,000 requests	per day (UTC)
Monthly quota	20,000 requests	per calendar month

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

Batch requests consume one unit per item. A batch of 20 hotels counts as 20 against every limit.

Polling is free. Only job-submitting calls consume rate limit and quota — poll endpoints, batch results and /usage/ are never counted.

Errors

Status	Meaning
`400`	Invalid input — validation error, with a per-field `detail`.
`401`	Missing or invalid API key.
`403`	API key deactivated.
`404`	Job not found (or not owned by your key).
`429`	Rate limit or quota exceeded.
`500`	Unexpected server error.

Fail-soft results. A scrape that finds nothing is not an HTTP error. Polls always return 200: a job ends completed with an empty result (e.g. no_results, sold_out: true) or failed with a human-readable error_message. Read each scraper's page for specifics.

Usage endpoint

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

GET /api/v1/scraper/usage/?days=30

GET /api/v1/flight-scraper/usage/?days=30

200 OK

{
  "client": "Your Company Name",
  "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 capped at 90.

Surface difference: the bandwidth fields (lifetime.total_bandwidth_kb, per-day total_bandwidth_kb) exist on the Hotel API only. The Flight API usage response reports requests, successes, failures and durations — no bandwidth accounting.

Ready to dive in? Pick a scraper: Google Hotels · Google Flights · Hotel Rates.