Getting started with the Google Search API

This guide walks through a first request to the Google Search API, the handful of parameters that change what comes back, and the shape of the response. All you need is an API key from your dashboard.

Your first request

curl "https://www.searchapi.io/api/v1/search?engine=google&q=coffee&api_key=YOUR_API_KEY"

The key can travel in the query string as above or in an Authorization: Bearer YOUR_API_KEY header. The response is a JSON document describing the results page Google returned for the query, as seen from the United States, in English, on a desktop browser. Those are the defaults: gl=us, hl=en and device=desktop.

The parameters that change results

Google shows different pages to different people. These are the parameters that control which page you get:

• location sets the canonical location of the search, for example location=London. The Locations API lists the accepted names; if several match, the most popular one is used. For precise control pass your own Google-encoded uule, or latitude and longitude in decimal degrees. The three are mutually exclusive.
• gl and hl set the country and the interface language. Google phased out country domains such as google.de in April 2025, so these two parameters are the way to localize a search.
• device switches between desktop, mobile and tablet. Mobile pages carry different blocks and often a different order.
• page selects the page of results. num is constant at 10 since Google phased it out in September 2025; the Google Rank Tracking API covers num=100.
• time_period restricts results by date, with time_period_min and time_period_max for a custom range in MM/DD/YYYY format.
• nfpr=1 drops results from auto-corrected queries, and verbatim=true goes further by disabling every query modification, including synonyms and personalization.
• safe toggles SafeSearch: active, blur (the default) or off.

Putting a few together:

curl "https://www.searchapi.io/api/v1/search?engine=google&q=coffee&location=London&gl=gb&hl=en&device=mobile&api_key=YOUR_API_KEY"

Reading the response

Every successful search returns the same core keys:

• search_metadata has the search id, status, the timings, and two links: html_url, the exact page that was parsed, and json_url, this response again. Keep the id; it is how you re-open a search later.
• search_parameters echoes the parameters as applied, defaults included, so you can see what gl or device actually was.
• search_information is what Google reported about the query: query_displayed, total_results, time_taken_displayed and, when a location was set, detected_location.
• organic_results is the list of results in order. Each has position, title, link, domain, displayed_link, snippet and favicon.
• pagination has current and next.

Anything else on the page, such as a knowledge panel, an answer box or People also ask, shows up as its own top-level key only when Google shows it. A short Ruby example that prints the organic results:

require "net/http"
require "json"

uri = URI("https://www.searchapi.io/api/v1/search")
uri.query = URI.encode_www_form(engine: "google", q: "coffee", location: "London", api_key: ENV.fetch("SEARCHAPI_KEY"))

data = JSON.parse(Net::HTTP.get(uri))
data["organic_results"].each do |result|
  puts "#{result["position"]}. #{result["title"]} - #{result["link"]}"
end

Where to go next

The Google Search API documentation lists every parameter and has a full example response for each block Google can show, from knowledge graph variants to AI Overview and local results. When a field you expect is missing, open search_metadata.html_url first: if the block is not on the page, there is nothing to parse.