API conventions
Base URL
Section titled “Base URL”https://api.scrapier.io/api/v2Every endpoint lives at /{slug}/, for example https://api.scrapier.io/api/v2/google-maps/. All traffic is HTTPS and all responses are UTF-8 JSON.
The trailing slash is required
Section titled “The trailing slash is required”Always end the path with /: /google-maps/, not /google-maps. Without it, the server redirects, and a POST may lose its body on the way. Every example in these docs keeps the slash.
GET or POST
Section titled “GET or POST”Both work on every endpoint, with the same parameters.
- GET: send the parameters in the query string.
- POST: send a JSON object in the body with
Content-Type: application/json. If you also send a query string, the body values win.
# GETcurl -G "https://api.scrapier.io/api/v2/google-maps/" \ -H "X-API-Key: YOUR_API_KEY" \ --data-urlencode "queries=coffee shops" \ --max-time 210
# POST JSONcurl -X POST "https://api.scrapier.io/api/v2/google-maps/" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"queries": "coffee shops"}' \ --max-time 210const res = await fetch("https://api.scrapier.io/api/v2/google-maps/", { method: "POST", headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" }, body: JSON.stringify({ queries: "coffee shops" }), signal: AbortSignal.timeout(210_000),});const body = await res.json();import requests
resp = requests.post( "https://api.scrapier.io/api/v2/google-maps/", headers={"X-API-Key": "YOUR_API_KEY"}, json={"queries": "coffee shops"}, timeout=210,)body = resp.json()One value per parameter
Section titled “One value per parameter”Some parameters have plural names, like urls, queries and usernames. They still take one value per call. To scrape ten profiles, make ten calls.
If you repeat a key in the query string (?urls=a&urls=b), only the last value is used. It doesn’t batch.
Booleans
Section titled “Booleans”Send booleans as the strings true or false. Other values such as 1 or yes aren’t guaranteed to work. For example, use_proxy=1 is treated as false.
Ignored parameters
Section titled “Ignored parameters”api_key and format are stripped from every request. Your key always goes in the X-API-Key header (Authentication), and responses are always JSON.
Response envelope
Section titled “Response envelope”A successful call returns HTTP 200:
{ "success": true, "data": { "queries": "coffee shops", "places": [ { "name": "Blue Bottle Coffee", "rating": 4.4 } ], "next_cursor": "eyJpIjoicXVlcnkiLCJwIjoyfQ" }}dataholds the page. Many endpoints echo your inputs (likequeries) next to the results.- The result key differs per endpoint:
places,posts,products,reviews,profile… There is no universalresultskey. Each endpoint page tells you which key to read. data.next_cursoris always present. It’snullon the last page or for single lookups. See Pagination.
Errors use a non-2xx status and a different body. See Errors.
Raw upstream payload (raw_data)
Section titled “Raw upstream payload (raw_data)”Every endpoint accepts an optional boolean raw_data, false by default. Set it to true to get the raw upstream payload(s) the scraper received (API bodies, HTML, embedded JSON) under raw_responses, in place of the formatted items. Pagination works the same in both modes. The sample on each endpoint page shows the default, formatted response. In GET /endpoints, sample_output carries both variants as { "formatted": {...}, "raw": {...} }; data in a normal call is the formatted one.