Search

See also the API reference for more detail.

Service usage

Massive‘s search service delivers all organic and paid result types from popular search engines, reliably, as structured or raw data. The service has a RESTful interface that accepts GET requests at https://‍render.joinmassive.com/search. Searches can be localized with geotargeting parameters. They’re performed live by default or optionally queued for subsequent retrieval. Live searches take an average of a few seconds but may require multiple retries, in which case up to 3 minutes is allocated per API call. Usage data is published regularly.

Authentication

You can access the service by including your secret API token in an Authorization header:

Authorization: Bearer [API token here]

Here’s an example request that uses the common Curl command:

curl -H "Authorization: Bearer $MASSIVE_TOKEN" \
'https://render.joinmassive.com/search'\
'?terms=foo+bar+baz'

This endpoint autoscales; if you receive a 503 response, maintain traffic and expect errors to resolve within a minute.

Search parameters

Besides the geotargeting and scheduling params linked above, required and optional search params can be added in a standard query string. The keys and values Massive supports are as follows:

Key	Required	Value
`terms`	✅	The broad or exact word or phrase of up to 255 characters 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)
`engine`	⬜	The search engine to use, `google` or `bing` (coming soon); `google` is the default engine
`serps`	⬜	The number of results pages to retrieve, from `1` to `10` inclusive; `1` is the default count
`size`	⬜	The number of results per page to retrieve, from `0` to `100` inclusive; page size is unset by default
`offset`	⬜	The number of initial results to skip, from `0` to `100` inclusive; results aren’t offset by default
`device`	⬜	The name as returned by the devices resource of the device to emulate searching on (these names are case insensitive but must include form- or URL-encoded spaces and punctuation marks); device emulation is unused by default
`uule`	⬜	The proprietary encoded string for emulating the location to search from; if possible, the actual location is searched from not emulated; location emulation is unused by default
`language`	⬜	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
`display`	⬜	The commonly spelled name, two-letter ISO code, or Google code of the search interface’s display language (these names and codes are case insensitive but required to include form- or URL-encoded spaces and punctuation marks); the display language is unset by default or set to the language if given
`url`	⬜	The encoded URL of up to 2,047 characters of the results page to retrieve; if given, the URL overrides any of the above params
`awaiting`	⬜	The lazy result features to wait to load, an `ai` overview, “People also ask” `answers`, or sponsored `ads`; any AI overview, which can take significant time to generate, is awaited for a maximum of 1 minute; multiple features can be provided by repeating the key; lazy results aren’t awaited by default
`expiration`	⬜	The age in days of when to consider cached results expired, where `0` disables caching; `1` is the default number of days before expiration
`callback`	⬜	The encoded HTTP or HTTPS callback URL or Amazon SQS queue URL or ARN of up to 2,047 characters to notify when the (prerequisite) asynchronous results have been retrieved; any SQS queue must grant `sqs:SendMessage` permission to the `arn:aws:iam::180363035301:role/api-instance` AWS principal

Device emulation

The device param 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 params to https://‍render.joinmassive.com/search/devices:

curl -H "Authorization: Bearer $MASSIVE_TOKEN" \
'https://render.joinmassive.com/search/devices'

The API will return JSON that contains an alphabetized array of device names:

[
  "Blackberry PlayBook",
  "Blackberry PlayBook landscape",
  "BlackBerry Z30",
  "[Remaining device names here]"
]

Then, pass your device name of choice into your search request:

curl -H "Authorization: Bearer $MASSIVE_TOKEN" \
'https://render.joinmassive.com/search'\
'?terms=blackberry'\
'&device=Blackberry+PlayBook'

Response format

Search results are returned as rendered HTML. If you request multiple results pages that don’t feature infinite scrolling, the HTML of each page will be separated from the next by an empty line (\n\n).

Additional examples

Results omission

curl -H "Authorization: Bearer $MASSIVE_TOKEN" \
'https://render.joinmassive.com/search'\
'?terms=vpn+comparison'\
'&size=100'\
'&offset=20'

Alternative URL

curl -H "Authorization: Bearer $MASSIVE_TOKEN" \
'https://render.joinmassive.com/search'\
'?url=https%3A%2F%2Fwww.google.com%2Fsearch%3Fq%3Dfoo%2Bbar%2Bbaz%26hl%3Dfr%26gl%3Dfr%26ie%3DUTF-8'

Lazy results

curl -H "Authorization: Bearer $MASSIVE_TOKEN" \
'https://render.joinmassive.com/search'\
'?terms=how+tall+is+mount+everest%3F'\
'&awaiting=ai'\
'&awaiting=answers'

Push notification

curl -H "Authorization: Bearer $MASSIVE_TOKEN" \
'https://render.joinmassive.com/search'\
'?terms=amazon+simple+queue+service'\
'&callback=https://webhook.site/02e249f8-1faf-4fab-bcf5-78ce683e85a8'

Get started

Endpoints

Configuration

API Management

API Reference

Service usage

Authentication

Search parameters

Device emulation

Response format

Additional examples

Results omission

Alternative URL

Lazy results

Push notification

​Service usage

​Authentication

​Search parameters

​Device emulation

​Response format

​Additional examples

​Results omission

​Alternative URL

​Lazy results

​Push notification

Service usage

Authentication

Search parameters

Device emulation

Response format

Additional examples

Results omission

Alternative URL

Lazy results

Push notification