Advanced Features
Search service
Advanced Features
Search service
Extract live results from popular search engines
Usage
The search service has a RESTful interface that accepts GET 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 an Authorization header:
Authorization: Bearer [Insert API token here]
Here’s an example request that uses the common Curl command:
$ curl -H "Authorization: Bearer $MASSIVE_API_TOKEN" \
'https://beta.api.joinmassive.com/search?terms=foo'
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 |
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 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
The device 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:
$ curl -H "Authorization: Bearer $MASSIVE_API_TOKEN" \
'https://beta.api.joinmassive.com/search/devices'
The API will return JSON that contains an alphabetized array of device names:
[
"BlackBerry Z30",
"BlackBerry Z30 landscape",
"Galaxy Note 3",
"[Remaining device names here]"
]
Asynchronous mode
A search request that includes the mode=async key-value pair will be satisfied asynchronously:
$ curl -H "Authorization: Bearer $MASSIVE_API_TOKEN" \
'https://beta.api.joinmassive.com/search?terms=foo&mode=async'
In response, the API will provide a JSON job identifier:
{ "id": "078fd246-f0f7-44a0-aabb-cadd7b12454f" }
The job results or status can be requested at any time thereafter by passing a token and the identifier to https://beta.api.joinmassive.com/search/results:
$ curl -H "Authorization: Bearer $MASSIVE_API_TOKEN" \
'https://beta.api.joinmassive.com/search/results?id=078fd246-f0f7-44a0-aabb-cadd7b12454f'
The results, if ready, will be returned in the same format as synchronous results; otherwise, a JSON status message will be returned.
A retrieving status indicates that the search is in progress:
{ "status": "retrieving" }
A failed status indicates that the search was unsuccessful and the request should be retried:
{ "status": "failed" }
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).
JSON
If you set the output to JSON, your results will be parsed into nested objects as in the following example:
{
"query": "foo",
"approxResultsCount": 255000000,
"resultsCount": 43,
"results": [{
"type": "organic",
"page": 1,
"section": "main",
"feature": 1,
"position": 1,
"url": "https://foofighters.com/",
"title": "Foo Fighters",
"site": "Foo Fighters",
"visibleUrl": "https://foofighters.com",
"date": null,
"snippet": "Official website of Foo Fighters.",
"rating": null,
"votes": null,
"sitelinks": [{
"position": 1,
"url": "https://foofighters.com/tour-dates/",
"title": "Tour Dates"
}, {
"position": 2,
"url": "https://shop.foofighters.com/",
"title": "Shop"
}, {
"position": 3,
"url": "https://foofighters.com/news/",
"title": "News"
}, {
"position": 4,
"url": "https://foofighters.com/news/a-message-from-the-hawkins-family/",
"title": "A Message from The Hawkins..."
}],
"images": []
}, {
"type": "also-asked",
"page": 1,
"section": "main",
"feature": 2,
"position": 1,
"question": "What does foo mean?",
"answer": {
"heading": null,
"description": "Foo (pronounced FOO) is a term used by programmers as a placeholder for a value that can change, depending on conditions or on information passed to the program.",
"date": null,
"url": "https://www.techtarget.com/searchapparchitecture/definition/foo-in-software-programming#:~:text=Foo%20(pronounced%20FOO)%20is%20a,information%20passed%20to%20the%20program.",
"title": "What Is Foo in Software Programming? Definition from ...",
"site": "TechTarget",
"visibleUrl": "https://www.techtarget.com › searchapparchitecture › foo-..."
}
}, {
"type": "also-asked",
"page": 1,
"section": "main",
"feature": 2,
"position": 2,
"question": "What is the English word Foo?",
"answer": {
"heading": null,
"description": "noun (1) ˈfü(ˌ)fü plural -s. slang. : fool, ninny.",
"date": null,
"url": "https://www.merriam-webster.com/dictionary/foo-foo#:~:text=1%20of%202-,noun%20(1),%3A%20fool%2C%20ninny",
"title": "Foo-foo Definition & Meaning - Merriam-Webster",
"site": "Merriam-Webster",
"visibleUrl": "https://www.merriam-webster.com › dictionary › foo-foo"
}
}, {
"type": "also-asked",
"page": 1,
"section": "main",
"feature": 2,
"position": 3,
"question": "Why do Hispanics say \"foo\"?",
"answer": {
"heading": null,
"description": "Foo is the diminutive of “fool” (because that extra “L” makes it far too lengthy). It is a term of endearment and part of the common Southern California Latino vernacular. The use of “fool” is foreign to others. It can be taken as a challenge, especially if the wrong tone or cadence are used.",
"date": "Apr 11, 2022",
"url": "https://ouresquina.com/2022/a-head-nod-to-the-foos-friendly-or-not/#:~:text=Foo%20is%20the%20diminutive%20of,tone%20or%20cadence%20are%20used.",
"title": "A head nod to the Foos, friendly or not - Our Esquina",
"site": "Our Esquina",
"visibleUrl": "https://ouresquina.com › a-head-nod-to-the-foos-friendly-..."
}
}, {
"[Remaining “People also ask” results here]"
}, {
"type": "organic",
"page": 1,
"section": "main",
"feature": 3,
"position": 1,
"url": "https://en.wikipedia.org/wiki/Foo_Fighters",
"title": "Foo Fighters",
"site": "Wikipedia",
"visibleUrl": "https://en.wikipedia.org › wiki › Foo_Fighters",
"date": null,
"snippet": "Foo Fighters is an American rock band formed in Seattle in 1994. Founded as a one-man project by former Nirvana drummer Dave Grohl, the lineup now consists ...",
"rating": null,
"votes": null,
"sitelinks": [],
"images": [{
"position": 1,
"source": "[Image data here]",
"alt": "foo from en.wikipedia.org"
}]
}, {
"type": "organic",
"page": 1,
"section": "main",
"feature": 3,
"position": 2,
"url": "https://www.merriam-webster.com/dictionary/foo",
"title": "Foo Definition & Meaning",
"site": "Merriam-Webster",
"visibleUrl": "https://www.merriam-webster.com › dictionary › foo",
"date": null,
"snippet": "The meaning of FOO is Scottish variant of how.",
"rating": null,
"votes": null,
"sitelinks": [],
"images": [{
"position": 1,
"source": "[Image data here]",
"alt": "foo from www.merriam-webster.com"
}]
}, {
"type": "top-story",
"page": 1,
"section": "main",
"feature": 4,
"position": 1,
"url": "https://nypost.com/2024/09/10/entertainment/foo-fighters-dave-grohl-reveals-he-cheated-welcomed-baby-outside-of-marriage/",
"publisher": "New York Post",
"headline": "Foo Fighters’ Dave Grohl reveals he cheated on his wife, welcomed baby ‘outside’ of his marriage",
"date": "2 hours ago",
"image": "[Image data here]",
}, {
"type": "top-story",
"page": 1,
"section": "main",
"feature": 4,
"position": 2,
"url": "https://www.mirror.co.uk/3am/celebrity-news/breaking-dave-grohl-admits-cheating-33640293",
"publisher": "The Mirror",
"headline": "Foo Fighters' Dave Grohl admits cheating on wife as he reveals fathering secret baby",
"date": "3 hours ago",
"image": "[Image data here]",
}, {
"type": "top-story",
"page": 1,
"section": "main",
"feature": 4,
"position": 3,
"url": "https://www.nbcnews.com/news/us-news/dave-grohl-announces-become-father-baby-born-marriage-rcna170498",
"publisher": "NBC News",
"headline": "Dave Grohl announces he's become the father of a baby born outside his marriage",
"date": "1 hour ago",
"image": "[Image data here]",
}, {
"[Remaining “Top stories” results here]"
}, {
"[Remaining organic results here]"
}, {
"type": "also-searched",
"page": 1,
"section": "bottom",
"feature": 1,
"position": 1,
"url": "https://www.google.com/search?sca_esv=7f94d02cc2bb7a85&sca_upv=1&q=Dave+Grohl&stick=H4sIAAAAAAAAAOMwVGI0-MXIsIGF4RULFxeHfq6-gZGFafIrFm4uThDHMKUiLRkulWRYVQXnpJQVFsI5llm5FnCOWW6WCZxjbpyOUGZSlFyEMNvIoKgKzksxtDTOWMTK5ZJYlqrgXpSfkXOLTZKh-2mPcWB8SME7leaDUof2LHlq8nPd7DLvVYs4xAJS8wtyUhUSc4rzFYpTE4uSMxTS8osAI_QNztIAAAA&sa=X&ved=2ahUKEwi1vO_B_5yIAxV8ElkFHRySAR4Qs9oBKAB6BAhkEAk",
"query": "Dave Grohl"
}, {
"type": "also-searched",
"page": 1,
"section": "bottom",
"feature": 1,
"position": 2,
"url": "https://www.google.com/search?sca_esv=7f94d02cc2bb7a85&sca_upv=1&q=Taylor+Hawkins&stick=H4sIAAAAAAAAAOMwVGI0_MXIsIGF4RULFxeHfq6-gZGFafIrFm4uThDHMKUiLRkulWRYVQXnpJQVFsI5llm5FnCOWW6WCZxjbpyOUGZSlFyEMNvIoKgKzksxtDTOWMTKF5JYmZNfpOCRWJ6dmVd8i02Softpj3FgfEjBO5Xmg1KH9ix5avJz3ewy71WLOMQCUvMLclIVEnOK8xWKUxOLkjMU0vKLAL7S69nWAAAA&sa=X&ved=2ahUKEwi1vO_B_5yIAxV8ElkFHRySAR4Qs9oBKAB6BAhkEA4",
"query": "Taylor Hawkins"
}, {
"type": "also-searched",
"page": 1,
"section": "bottom",
"feature": 1,
"position": 3,
"url": "https://www.google.com/search?sca_esv=7f94d02cc2bb7a85&sca_upv=1&q=Nirvana+(band)&stick=H4sIAAAAAAAAAOMwVGI0-sXIsIGF4RULFxeHfq6-gZGFafIrFm4uThDHMKUiLRkulWRYVQXnpJQVFsI5llm5FnCOWW6WCZxjbpyOUGZSlFyEMNvIoKgKzksxtDTOWMTK55dZVJaYl6igkZSYl6J5i02Softpj3FgfEjBO5Xmg1KH9ix5avJz3ewy71WLOMQCUvMLclIVEnOK8xWKUxOLkjMU0vKLAJ7k8YDWAAAA&sa=X&ved=2ahUKEwi1vO_B_5yIAxV8ElkFHRySAR4Qs9oBKAB6BAhkEBM",
"query": "Nirvana"
}, {
"[Remaining “People also search for” results here]"
}]
}
Additional examples
$ curl -H "Authorization: Bearer $MASSIVE_API_TOKEN" \
'https://beta.api.joinmassive.com/search?terms=foo+bar+baz&serps=2&engine=bing'
$ curl -H "Authorization: Bearer $MASSIVE_API_TOKEN" \
'https://beta.api.joinmassive.com/search?terms=%22foo+bar+baz%22&serps=10&engine=duckduckgo&country=us&format=json'