serpapi-python¶

an official Python client library for SerpApi.

Installation¶

To install serpapi-python, simply use pip:

$ pip install serpapi

Please note that Python 3.6+ is required.

Usage¶

Usage of this module is fairly straight-forward. In general, this module attempts to be as close to the actual API as possible, while still being Pythonic.

For example, the API endpoint https://serpapi.com/search.json is represented by the method serpapi.search().

>>> import serpapi
>>> s = serpapi.search(q="Coffee", engine="google", location="Austin, Texas", hl="en", gl="us")
>>> s["organic_results"][0]["link"]
'https://en.wikipedia.org/wiki/Coffee'

Any parameters that you pass to search() will be passed to the API. This includes the api_key parameter, which is required for all requests.

To make this less repetitive, and gain the benefit of connection pooling, let’s start using the API Client directly:

>>> client = serpapi.Client(api_key="secret_api_key")
>>> s = client.search(q="Coffee", engine="google", location="Austin, Texas", hl="en", gl="us")

The api_key parameter is now automatically passed to all requests made by the client.

Concise Tutorial¶

Let’s start by searching for Coffee on Google:

>>> import serpapi
>>> s = serpapi.search(q="Coffee", engine="google", location="Austin, Texas", hl="en", gl="us")

The s variable now contains a SerpResults object, which acts just like a standard dictionary, with some convenient functions added on top.

Let’s print the first result:

>>> print(s["organic_results"][0]["link"])
https://en.wikipedia.org/wiki/Coffee

Let’s print the title of the first result, but in a more Pythonic way:

>>> print(s["organic_results"][0].get("title"))
Coffee - Wikipedia

The SerpApi.com API Documentation contains a list of all the possible parameters that can be passed to the API.

API Reference¶

This part of the documentation covers all the interfaces of serpapi Python module.

serpapi.search(**params)¶

Fetch a page of results from SerpApi. Returns a SerpResults object, or unicode text (e.g. if 'output': 'html' was passed).

The following two calls are equivalent:

>>> s = serpapi.search(q="Coffee", location="Austin, Texas, United States")

>>> params = {"q": "Coffee", "location": "Austin, Texas, United States"}
>>> s = serpapi.search(**params)

Parameters:

q – typically, this is the parameter for the search engine query.
engine – the search engine to use. Defaults to google.
output – the output format desired (html or json). Defaults to json.
api_key – the API Key to use for SerpApi.com.
** – any additional parameters to pass to the API.

Learn more: https://serpapi.com/search-api

serpapi.search_archive(**params)¶

Get a result from the SerpApi Search Archive API.

Parameters:

search_id – the Search ID of the search to retrieve from the archive.
api_key – the API Key to use for SerpApi.com.
output – the output format desired (html or json). Defaults to json.
** – any additional parameters to pass to the API.

Learn more: https://serpapi.com/search-archive-api

serpapi.locations(**params)¶

Get a list of supported Google locations.

Parameters:

q – restricts your search to locations that contain the supplied string.
limit – limits the number of locations returned.
** – any additional parameters to pass to the API.

Learn more: https://serpapi.com/locations-api

serpapi.account(**params)¶

Get SerpApi account information.

Parameters:

api_key – the API Key to use for SerpApi.com.
** – any additional parameters to pass to the API.

Learn more: https://serpapi.com/account-api

Results from SerpApi.com¶

When a successful search has been executed, the method returns a SerpResults object, which acts just like a standard dictionary, with some convenient functions added on top.

>>> s = serpapi.search(q="Coffee", engine="google", location="Austin, Texas", hl="en", gl="us")
>>> type(s)
<class 'serpapi.models.SerpResults'>

>>> s["organic_results"][0]["link"]
'https://en.wikipedia.org/wiki/Coffee'

>>> s["search_metadata"]
{'id': '64c148d35119a60ab1e00cc9', 'status': 'Success', 'json_endpoint': 'https://serpapi.com/searches/a15e1b92727f292c/64c148d35119a60ab1e00cc9.json', 'created_at': '2023-07-26 16:24:51 UTC', 'processed_at': '2023-07-26 16:24:51 UTC', 'google_url': 'https://www.google.com/search?q=Coffee&oq=Coffee&uule=w+CAIQICIdQXVzdGluLFRYLFRleGFzLFVuaXRlZCBTdGF0ZXM&hl=en&gl=us&sourceid=chrome&ie=UTF-8', 'raw_html_file': 'https://serpapi.com/searches/a15e1b92727f292c/64c148d35119a60ab1e00cc9.html', 'total_time_taken': 1.55}

Optionally, if you want exactly a dictionary of the entire response, you can use the as_dict() method:

>>> type(s.as_dict())
<class 'dict'>

You can get the next page of results:

>>> type(s.next_page())
<class 'serpapi.models.SerpResults'>

Or iterate over all pages of results:

>>> for page in s.yield_pages():
...     print(page["search_metadata"]["page_number"])
1
2
3
4
5
6
7
8
9
10

Here’s documentation of the class itself and its methods:

class serpapi.SerpResults(data, *, client)¶

A dictionary-like object that represents the results of a SerpAPI request.

>>> search = serpapi.search(q="Coffee", location="Austin, Texas, United States")

>>> print(search["search_metadata"].keys())
dict_keys(['id', 'status', 'json_endpoint', 'created_at', 'processed_at', 'google_url', 'raw_html_file', 'total_time_taken'])

An instance of this class is returned if the response is a valid JSON object. It can be used like a dictionary, but also has some additional methods.

next_page()¶: Return the next page of results, if any.

yield_pages(max_pages=1000)¶

A generator that yield s the next n pages of search results, if any.

Parameters:: max_pages – limit the number of pages yielded to n.

property next_page_url¶: The URL of the next page of results, if any.

API Client¶

The primary interface to serpapi-python is through the serpapi.Client class. The primary benefit of using this class is to benefit from Requests’ HTTP Connection Pooling. This class also alleviates the need to pass an api_key` along with every search made to the platform.

class serpapi.Client(*, api_key=None)¶

A class that handles API requests to SerpApi in a user–friendly manner.

Parameters:: api_key – The API Key to use for SerpApi.com.

Please provide api_key when instantiating this class. We recommend storing this in an environment variable, like so:

$ export SERPAPI_KEY=YOUR_API_KEY

import os
import serpapi

serpapi = serpapi.Client(api_key=os.environ["SERPAPI_KEY"])

search(**params)¶

Fetch a page of results from SerpApi. Returns a SerpResults object, or unicode text (e.g. if 'output': 'html' was passed).

The following two calls are equivalent:

>>> s = serpapi.search(q="Coffee", location="Austin, Texas, United States")

>>> params = {"q": "Coffee", "location": "Austin, Texas, United States"}
>>> s = serpapi.search(**params)

Parameters:

q – typically, this is the parameter for the search engine query.
engine – the search engine to use. Defaults to google.
output – the output format desired (html or json). Defaults to json.
api_key – the API Key to use for SerpApi.com.
** – any additional parameters to pass to the API.

Learn more: https://serpapi.com/search-api

search_archive(**params)¶

Get a result from the SerpApi Search Archive API.

Parameters:

search_id – the Search ID of the search to retrieve from the archive.
api_key – the API Key to use for SerpApi.com.
output – the output format desired (html or json). Defaults to json.
** – any additional parameters to pass to the API.

Learn more: https://serpapi.com/search-archive-api

account(**params)¶

Get SerpApi account information.

Parameters:

api_key – the API Key to use for SerpApi.com.
** – any additional parameters to pass to the API.

Learn more: https://serpapi.com/account-api

locations(**params)¶

Get a list of supported Google locations.

Parameters:

q – restricts your search to locations that contain the supplied string.
limit – limits the number of locations returned.
** – any additional parameters to pass to the API.

Learn more: https://serpapi.com/locations-api

Exceptions¶

exception serpapi.SerpAPIError¶: Base class for exceptions in this module.

exception serpapi.SearchIDNotProvided¶: Search ID is not provided.

exception serpapi.HTTPError(*args, **kwargs)¶: HTTP Error.

exception serpapi.HTTPConnectionError(*args, **kwargs)¶: Connection Error.

serpapi-python¶

Installation¶

Usage¶

Concise Tutorial¶

API Reference¶

Results from SerpApi.com¶

API Client¶

Exceptions¶

Indices and tables¶