Advanced Features
SERP API
Extract live results from popular search engines
Usage
The search service has a RESTful interface that acceptsGET requests at
https://beta.api.joinmassive.com/search.
Searches are performed in real time by default or can be queued for
later retrieval. Real-time searches take an average of a few seconds but may
require multiple retries, in which case up to 120 seconds is allocated per API request.
Authentication
You can access the service by including your secret API token in anAuthorization header:
Search parameters
Required and optional parameters can be added in a standard query string. The keys and values that Massive supports are as follows:| Key | Required | Value |
|---|---|---|
terms | ✅ | The broad or exact word or phrase to query (e.g., foo bar baz or "foo bar baz"); the terms require form or URL encoding (with any space character being replaced by a + character or %20 sequence) |
serps | ⬜ | The number of results pages to retrieve, from 1 to 10 inclusive; 1 is the default count |
size | ⬜ | [Google only] The number of results per page to retrieve, from 0 to 100 inclusive; page size is unset by default |
offset | ⬜ | [Google only] The number of initial results to skip, from 0 to 100 inclusive; results aren’t offset by default |
engine | ⬜ | The search engine to use, google, bing, or duckduckgo; google is the default engine |
device | ⬜ | [Google only] The name as returned by the devices endpoint of the device to emulate searching on (these names are case insensitive but must include form- or URL-encoded spaces and punctuation marks); searching is done on a desktop browser by default |
country | ⬜ | The two-letter ISO code of the country to search from (these codes are case insensitive); a random country will be used by default |
subdivision | ⬜ | The alphanumeric second part (proceeding the separator) of a first-level subdivision code in the (prerequisite) country to search from (these codes are case insensitive); a random subdivision will be used by default |
city | ⬜ | The commonly spelled name of the city in the (prerequisite) country to search from (these names are temporarily case sensitive and required to include form- or URL-encoded spaces and punctuation marks); a random city will be used by default |
uule | ⬜ | [Google only] The proprietary encoded string for emulating the location to search from; if possible, the actual location will be searched from not emulated; location emulation is unused by default |
language | ⬜ | [Google only] The commonly spelled name, two-letter ISO code, or Google code of the language to search in (these names and codes are case insensitive but required to include form- or URL-encoded spaces and punctuation marks); the language is unset by default |
mode | ⬜ | The synchronous or asynchronous timing of when to retrieve results, sync or async (see details below); sync is the default mode |
format | ⬜ | The format to output to, html or json (see details below); html is the default format |
expiration | ⬜ | The maximum age of cached results in days to accept, where 0 will disable caching; 1 is the default number of days |
subaccount | ⬜ | Any unique identifier of up to 255 characters (regardless of character encoding); Massive will bill requests made from subaccounts separately |
Device emulation
Thedevice parameter (which is currently limited to Google searches) lets you fetch
device-specific results, rather than the default desktop results. For a list of supported smartphone
and tablet devices, make a request with your API token and no parameters to
https://beta.api.joinmassive.com/search/devices:
Asynchronous mode
A search request that includes themode=async key-value pair will be satisfied asynchronously:
retrieving status indicates that the search is in progress:
failed status indicates that the search was unsuccessful and the request should be retried:
Response format
You can receive search results in their original HTML or as structured JSON.HTML
Google and Bing don’t feature infinite scrolling, so if you request more than one results page from those search engines, the HTML of each page will be separated from the next by an empty line (\n\n).