Parameters

Every endpoint is a GET and takes its fields as query parameters. Fields an endpoint does not use are ignored. A parameter that is missing or refused answers 400 with {"error": "..."} and must not be retried. The per-field limits and 400 messages are in each endpoint's page in the API Reference.

Query parametersCopy Anchor Link

The fields on this page are query parameters, for example ?q=coffee&gl=us.

• Values must be URL-encoded: location=Austin%2CTexas%2CUnited%20States. In curl, -G with --data-urlencode does it for you. URLSearchParams (JavaScript), params= in requests (Python) and http_build_query (PHP) do too.
• A number or true/false is read as the type the field takes.
• A list repeats its parameter: include=a&include=b.
• An object field is sent as field[key]=value: business[name]=Joe.
• A list or an object can also be sent as one JSON string.

curl -G "https://api.justserp.com/v1/google/maps/place" \
  -H "X-API-Key: YOUR_API_KEY" \
  --data-urlencode "place_id=ChIJ..." \
  --data-urlencode "include=hours" \
  --data-urlencode "include=photos"

Two request formsCopy Anchor Link

Many endpoints accept two sets of parameters: their own, described on this page, and a document form that uses common SERP-API names (for example q where the first form has query). Both are answered as the document. A request takes one form: sending query together with q is a 400. Each endpoint's page in the API Reference lists both forms and says which fields select the document form.

Google Search has only the document form, described below.

Fields shared by every endpointCopy Anchor Link

Google SearchCopy Anchor Link

GET /v1/google/search. One request is one results page, answered as the document.

Send q or kgmid. Place the search with at most one of location, uule, or latitude with longitude.

api_version (v1 or v2) is deprecated. Sending it selects the earlier call, which takes google_domain, start and tbs and answers in an envelope with the result in data. Leave it out to get the document.

Reference: Google Search. For a lighter answer with fewer blocks, see Google Light.

Google Maps, Trends and placesCopy Anchor Link

• Maps search (q required; latitude and longitude are sent together or not at all; zoom 3 to 21, default 14; leave hl at en; gl is the country): Google Maps. A search that matches exactly one place answers that place, not a list. In the document form, send q with ll (@latitude,longitude,zoom) instead of latitude, longitude and zoom.
• Trends (q for a keyword's related queries and topics, geo alone for a region's trending searches; at least one is required; date is Explore's time range such as today 12-m; leave hl at en): Google Trends.
• Place details and Google reviews name a place by one of place_id, data_id or data_cid. Place details takes them in that order and also takes country and include: Maps place. Google reviews also accepts a profile_url this path returned before: Maps reviews.

Refused ids answer 400 with place_id is not a Google place id, data_id is not a feature id (0x...:0x...) or data_cid is not a CID (a whole number).

include on place details lists the sections to return: hours, attributes, services, photos, questions, social. The default is all. A section left out is null ("not loaded"), and an unknown name is refused.

AI answersCopy Anchor Link

Google AI Overview, Google AI Mode and ChatGPT share one request: a query and an optional location.

curl -G "https://api.justserp.com/v1/google/ai-overview" \
  -H "X-API-Key: YOUR_API_KEY" \
  --data-urlencode "query=Who has the best pizza near Chelsea, New York, NY?" \
  --data-urlencode "location[latitude]=40.7455" \
  --data-urlencode "location[longitude]=-74.0083" \
  --data-urlencode "location[name]=New York, NY" \
  --data-urlencode "location[country]=us" \
  --data-urlencode "location[language]=en"

query is required, 1 to 2000 characters after trimming (query is too long (2000 characters at most)).

location is an object whose every part is optional; a part left out, null or "" is not an error. latitude and longitude are sent together or not at all.

A location that is not an object answers location must be an object; one with only one of latitude and longitude answers location.latitude and location.longitude must be sent together.

For ChatGPT, name the town in query: a "near me" question is answered for wherever the request was made from.

In the document form, send the question as q instead of query. Google AI Overview and AI Mode then take location, uule or latitude with longitude like Google Search, and ChatGPT takes country. Each endpoint's page lists the rest.

Reference: AI Overview, AI Mode, ChatGPT. Bing Copilot takes its own parameters; see its page.

ReviewsCopy Anchor Link

Every review endpoint takes a profile_url (Google takes a place id instead, see above) plus these shared options:

A profile that does not exist answers 404 profile_not_found.

A profile_url that does not match its site answers 400, e.g. profile_url must be a Facebook page, profile_url must be a bbb.org business profile, profile_url must be a Yelp business page.

Finding a profileCopy Anchor Link

Where there is a "find" endpoint, send the business and the endpoint returns up to 5 candidate profiles to use as profile_url.

curl -G "https://api.justserp.com/v1/google/maps/reviews/find" \
  -H "X-API-Key: YOUR_API_KEY" \
  --data-urlencode "business[name]=Joe's Pizza Broadway" \
  --data-urlencode "business[address]=1435 Broadway, New York, NY 10018" \
  --data-urlencode "business[phone]=+1 212-366-1182" \
  --data-urlencode "business[website]=http://joespizzanyc.com/" \
  --data-urlencode "business[latitude]=40.7546795" \
  --data-urlencode "business[longitude]=-73.9870291" \
  --data-urlencode "country=us"

business.name is required. How each site uses the rest:

• Google: searches Maps for name and address, around latitude and longitude when given.
• Trustpilot: searches by the domain of website when sent, else by name.
• BBB: name and the town from address. country ca searches Canada, anything else the USA.
• Yellow Pages: name and "City, ST" from address.
• Healthgrades: name as "who" and the town from address as "where". The candidates are providers.
• Facebook: Facebook has no search a visitor can use, so this reads website for links to the page. load_candidates (default false) opens up to 3 pages found to fill in name, address and phone.

phone is not searched with; it is for your own matching. Angi, Tripadvisor and Yelp have no find.

YelpCopy Anchor Link

• Yelp search: location is required (location is required: the place to search, e.g. "Austin, TX"), and one of query or category (query (or category) is required in the request body). Optional: start (0 to 1000, default 0, 10 for the second page), sort_by (recommended, rating or review_count), attrs, country. In the document form, send q and location with page (1 to 24) instead.
• Yelp business page: place_id (Yelp's id or alias, which search returns in place_ids) or profile_url, plus country. Add yelp_domain: "yelp.com" for the document form.
• Yelp reviews: profile_url and the shared review options. In the document form, send Yelp's 22-character place_id and no profile_url.

CancellingCopy Anchor Link

GET /v1/cancel takes ?cancel_token=.... See Errors & billing.