> ## Documentation Index
> Fetch the complete documentation index at: https://docs.joinmassive.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Search

> Extract top real-time search results.

export const Autoscaling = () => {
  return <Warning>
      This endpoint autoscales; if you receive a <code>503</code> response, maintain traffic and
      expect errors to resolve within a couple minutes.
    </Warning>;
};

export const Reference = ({endpoint}) => {
  return <Info>
      See also the <Link href={`reference/${endpoint}`}>API reference</Link> for more detail.
    </Info>;
};

export const apiEndpoint = 'render.joinmassive.com';

export const companyName = 'Massive';

<Reference endpoint="search" />

## Service usage

**{companyName}'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\://‍{apiEndpoint}/search**.

Searches can be localized with <Link href="geotargeting">geotargeting parameters</Link>. They're
performed live by default or optionally queued for <Link href="scheduling">subsequent
retrieval</Link>. 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. <Link href="usage">Usage data</Link> is
published regularly.

### Authentication

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

```http theme={null}
Authorization: Bearer [API token here]
```

Here's an example request that uses the [common Curl command](https://curl.se/):

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

<Autoscaling />

### Search parameters

Besides the [geotargeting and scheduling params linked above](#service-usage), required and optional
search params can be added in a
[standard query string](https://developer.mozilla.org/en-US/docs/Learn/Common_questions/What_is_a_URL#parameters).
The keys and values **{companyName}** 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](https://developer.mozilla.org/en-US/docs/Glossary/Percent-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`       | ⬜        | 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                                                                                                                                                                                                                                                                                                             |
| `uule`       | ⬜        | The [proprietary encoded string](https://moz.com/blog/geolocation-the-ultimate-tip-to-emulate-local-search) 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](https://www.loc.gov/standards/iso639-2/php/code_list.php), or [Google code](https://www.google.com/advanced_search) 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](https://www.loc.gov/standards/iso639-2/php/code_list.php), or [Google code](https://www.google.com/advanced_search) 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 |
| `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                                                                                                                                                                                                                                                                      |

### 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

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

### Lazy results

```shell theme={null}
curl -H "Authorization: Bearer $MASSIVE_TOKEN" \
'https://render.joinmassive.com/search'\
'?terms=how+tall+is+mount+everest'\
'&awaiting=ai'\
'&awaiting=answers'
```