Google Search API: From Search Queries to Structured JSON

TL;DR:

• Scrapeless Google Search API returns search results as structured JSON. Use organic-result fields in research tools, SEO reports, and source-discovery workflows.
• Search context belongs with the result. Keep the query, country, language, and observation time together so later comparisons have a clear meaning.
• A pending task is different from an empty result set. Handle HTTP 201 separately before trying to read organic_results or create a CSV.

Google search data becomes useful when a team can connect each result to the question and market that produced it. A title and URL copied into a spreadsheet lose much of that context. A structured response lets an application preserve it from the start.

The updated Scrapeless Google Search API provides a managed route from a search query to JSON. Your application sends the request and decides how to use the returned data. Proxy and CAPTCHA handling run on the service side, reducing the collection infrastructure your team needs to maintain.

This guide follows that handoff: choose a search context, submit a request, read the response, and save a dataset that another person can understand.

What the Google Search API Returns

Google Search API returns structured search data, with organic results available in the top-level organic_results array when present. A natural result can include position, title, link, and snippet. The response can also contain pagination information and other search modules, depending on the query and the results returned.

Keep the original response before extracting a subset. A flat table is convenient for analysis, but it cannot represent every nested object without a deliberate mapping. The JSON data model distinguishes arrays, objects, strings, numbers, booleans, and null; preserving those distinctions makes later processing easier.

A snippet is a search-result excerpt. It does not supply the full content of the destination page. If a research application needs an article's evidence, the application must obtain and review that page separately.

Prepare a Small First Request

A first request needs a Scrapeless API key, a query, and a client that can send JSON over HTTP. Use an account with access to the Google Search API and keep the key in the SCRAPELESS_API_KEY environment variable.

For the Python example below, install the requests package in your project environment. The remaining modules come from Python's standard library. Save the script as google_search_export.py, then run it with python3 google_search_export.py after setting the environment variable through your local shell or secret manager.

The example uses the neutral query coffee, country us, and language en. Start with this small input before introducing a list of keywords or a scheduled job. Inspect the response shape first; the downstream data model depends on it.

The authenticated request is a prerequisite that requires your own account key. The example's request shape follows the current API reference; it is not presented as a captured live account run.

Choose Country, Language, and Input Mode

Country, language, and location describe different parts of a search request. gl selects the search country, hl selects the search language, and location specifies where the search should originate. google_domain selects the Google domain. The current device option supports desktop.

The Google Search API parameter model also has two input rules that affect how you construct requests:

• Use q for a query expressed through individual parameters. Alternatively, provide a complete Google Search url; when url is supplied, other input parameters are ignored.
• Choose either location or uule. They cannot be used together.

For a comparison across markets, save the complete input object with each response. Setting the same country and language makes the intended context explicit, but it does not guarantee identical results across observations or reproduce a particular person's signed-in search history.

Queries can include operators such as site:, inurl:, and intitle:. Use them to narrow a research question. A site-restricted search is not a complete inventory of indexed pages, so its results should not become an exact index-coverage count.

Request JSON and Export Organic Results

The request uses POST https://api.scrapeless.com/api/v1/scraper/request, the scraper.google.search actor, and an x-api-token header. The script saves the response with its input and receipt time, then exports the organic results to CSV after HTTP 200.

Note: The network request requires your Scrapeless API key and has not been executed with a live account for this article. The script preserves an HTTP 201 task response for inspection; it does not implement task-result retrieval.

import csv
import json
import os
from datetime import datetime, timezone
from pathlib import Path

import requests


def spreadsheet_text(value):
    text = "" if value is None else str(value)
    if text.lstrip().startswith(("=", "+", "-", "@")) or text.startswith(("\t", "\r")):
        return "'" + text
    return text


def export_results(payload, context, received_at, output_path):
    results = payload.get("organic_results")
    if not isinstance(results, list):
        print("No usable organic_results array; inspect the saved JSON.")
        return
    fields = ["q", "gl", "hl", "received_at", "position", "title", "link", "snippet"]
    with output_path.open("w", encoding="utf-8", newline="") as stream:
        writer = csv.DictWriter(stream, fieldnames=fields)
        writer.writeheader()
        for item in results:
            if not isinstance(item, dict):
                raise ValueError("Unexpected organic result item; inspect the saved JSON.")
            row = {name: item.get(name) for name in ("position", "title", "link", "snippet")}
            row.update(context, received_at=received_at)
            writer.writerow({name: spreadsheet_text(row.get(name)) for name in fields})
    print(f"Exported {len(results)} organic results to {output_path}")


def main():
    context = {"q": "coffee", "gl": "us", "hl": "en"}
    response = requests.post(
        "https://api.scrapeless.com/api/v1/scraper/request",
        headers={"x-api-token": os.environ["SCRAPELESS_API_KEY"]},
        json={"actor": "scraper.google.search", "input": context},
        timeout=120,
    )
    response.raise_for_status()
    received_at = datetime.now(timezone.utc).isoformat()
    run_id = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%S%fZ")
    payload = response.json()
    record = {"input": context, "received_at": received_at,
              "http_status": response.status_code, "response": payload}
    output = Path(f"google-search-{run_id}.json")
    output.write_text(json.dumps(record, ensure_ascii=False, indent=2), encoding="utf-8")
    if response.status_code == 201:
        print(f"Task pending. Inspect taskId in {output}; no CSV was created.")
        return
    if response.status_code != 200 or not isinstance(payload, dict):
        raise ValueError(f"Unexpected response; inspect {output}")
    export_results(payload, context, received_at, output.with_suffix(".csv"))


if __name__ == "__main__":
    main()

The 120 timeout is a client setting in this example, not a service response-time promise. Receipt time is recorded by the client after the response arrives; it is not a timestamp supplied by Google.

Python's CSV writer handles delimiters and quoted fields. The helper also prefixes common spreadsheet formula markers in exported text. Preserve the JSON as the original record, because the CSV is a transformed view intended for inspection. Review text-import settings before opening externally sourced values in a spreadsheet.

The example exports only q, gl, and hl from its input. If you add a location, domain, or pagination offset, extend the CSV columns to retain those dimensions too. The saved JSON already contains the full input object.

Interpret the Response Before Building a Report

An HTTP 200 response contains the task data, while HTTP 201 indicates processing and provides a taskId. A pending task should not create an empty-results observation. The script keeps its JSON record and skips CSV export in that case.

For successful data responses, distinguish an empty array from an absent or unusable organic_results field. Other modules may still be present. The script preserves the response and asks you to inspect it when no usable array exists.

Read position as the position supplied for that returned result. Before combining pages into a global rank, verify how the endpoint numbers positions for your requests. start controls the result offset, and pagination information can guide subsequent requests; neither establishes that every Google result can be retrieved.

Put Structured Search Data to Work

Structured search results provide inputs for workflows your application builds around the API. The useful unit is a result plus its request context and observation time.

• SEO snapshots: save observations for a fixed keyword list, then compare matching contexts over time. Scheduling, storage, and change detection belong to your pipeline.
• Brand and competitor research: review which domains and page titles appear for your selected queries. The sample describes those searches, rather than all web mentions or a site's traffic.
• AI source discovery: pass candidate titles, links, and snippets into a source-selection step. Fetch full pages separately when evidence is needed, and check that generated claims match their sources.

For a content team, the first output could be a short reading list with the query and market attached. For a developer, it could be a repeatable export used by an existing report. Both start with a data record that makes its scope visible.

Use these examples for public information you are permitted to collect and use. Retain the fields needed for the task, protect credentials, and review the conditions that apply to downstream reuse.

Conclusion

Google Search API gives an application structured search data to work with. A useful integration also preserves the input, checks task state, and separates source discovery from later analysis. Begin with a single query and inspect the saved JSON before expanding the workflow.

The updated Google Search API request workflow provides the connection details for adapting this example to your own project.

FAQ

Q: Is this an API provided by Google?

This article describes Scrapeless Google Search API, a Scrapeless service for retrieving Google Search data. It does not claim an official Google partnership.

Q: Do you need to manage a browser or proxy?

The managed API handles the collection infrastructure on the service side. Your client sends HTTP requests and processes the returned data.

Q: Does the API include historical ranking data?

The workflow described here creates history by saving your own observations. It does not retrieve a pre-existing ranking history.

Q: Can the same API search for images?

The product supports Google Image searches, with tbm=isch identified in the parameter reference. Inspect the image response separately; this article's CSV mapping is for organic web results.

Q: Does a search snippet contain the full page?

A snippet is an excerpt associated with a search result. A workflow that needs the page's full evidence must obtain and review the destination content separately.

Q: What should happen when the request returns HTTP 201?

Preserve the taskId and treat the task as pending. Complete the documented task-result workflow before processing it as finished search data.