ProtoScrape's Google Search engine can return the same collection in two forms: parsed JSON, which is the default, or the raw HTML results page. Both cost one credit per successful job. This guide explains what each contains and when to use which.
Switch with one field
curl https://api.protoscrape.com/v1/jobs \
-H "Authorization: Bearer $PROTOSCRAPE_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: layout-audit-001" \
-d '{"engine":"google_serp","query":"project management software","output":"html"}'
Omit output, or set it to "json", for parsed results. Fetch either from GET /v1/jobs/{job_id}/result; the response's metadata.output tells you which form you received.
What parsed JSON contains
| Field | Contents |
|---|---|
organic |
Ordered results with position, title, url, snippet and domain |
people_also_ask |
The questions shown in the “People also ask” block |
related_searches |
Follow-up searches Google suggests |
People Also Ask answers load only when a user expands a question, so the parsed output contains the questions alone. Lists can be empty when Google shows no such block for a query.
What raw HTML contains
The html field is the results page exactly as it was collected, typically between a few hundred kilobytes and a few megabytes. It includes everything the parsed schema leaves out: AI Overviews, ads, local packs, knowledge panels, images and the precise layout.
When parsed JSON is the right choice
- Rank tracking and dashboards. Stable fields compare cleanly across dates.
- High volume. Records are small, fast to transfer and cheap to store.
- Spreadsheets and exports. CSV exports include the organic results as JSON in one column.
When raw HTML is worth it
- Auditing. Check a surprising ranking against the actual page.
- Features outside the schema. Detect whether an AI Overview, ad or local pack appeared, using your own extraction.
- Layout research. Measure how far down the page the first organic result sits.
- Archiving. Keep evidence of what a page showed at a given time.
Practical differences
| Parsed JSON | Raw HTML | |
|---|---|---|
| Size | A few kilobytes | Hundreds of kilobytes to a few megabytes |
| Where to read it | Result endpoint, exports and webhooks | Result endpoint only |
| Exports and webhooks | Full results | output and html_bytes |
| Batches and schedules | Supported | Single jobs only |
| Speed | Includes resolving result links | Usually faster |
Exports and webhooks carry a size note for HTML jobs rather than megabytes of markup; fetch the page from the result endpoint when you need it. Results are retained for about seven days, so store pages you want to keep.
Previewing a page safely
Treat collected HTML as untrusted content. Never insert it into your own site's pages, where its markup could interfere with your application. If you need to display it, use a sandboxed frame with scripts disabled. The ProtoScrape workspace does exactly that: the API playground's Result preview shows the collected page in a sandbox, with scripts and links disabled, and offers a download.
Start with parsed JSON for routine collection and request HTML for the queries you need to inspect. See the API documentation for the complete schema. ProtoScrape is independent and is not affiliated with Google.