Skip to content

Fast Search API

This reference explains how to call the Fast Search API, which parameters are required, how results are localized and paginated, what the JSON response contains, and what each successful call costs in API credits. Use it as a build checklist before wiring the endpoint into a script or integration.

Overview

The Fast Search API accepts a search string and returns structured search results as JSON. Requests are authenticated with a private API key sent as a Bearer token in the Authorization header. The endpoint is a GET request to the fast_search path on the configured application base URL.

The parameter set is small: two required values (api_key and search) and three optional values (country_code, page and tag). That makes the API easy to embed in a script, but the optional parameters change behavior in different ways, so it helps to separate them before you build.

Parameter map and decision checklist

Use this checklist to decide what to send and what to expect.

  • api_key (string, required): your private API key. Send it as a Bearer token in the Authorization header. The deprecated api_key query parameter is covered in the Authentication documentation.
  • search (string, required): the text you would put in a search bar. URL-encode it, especially when it contains characters such as :, & or +.
  • country_code (string, default "us"): localizes results to a country using ISO 3166-1 alpha-2 codes such as us, fr or de.
  • page (integer, default 1): selects which page of results to extract. Use page=2 for the second page.
  • tag (string, default ""): an optional custom identifier returned with the response headers. It does not change scraping behavior.

Decision checklist:

  1. Always send api_key and search.
  2. Set country_code when the search intent is tied to a country; otherwise the default is us.
  3. Set page only when you need results beyond the first page.
  4. Set tag when you want to correlate a request with a response header, not to alter results.
  5. URL-encode the search value before sending it.

Getting started

To make a request you need two things: an API key and a search query. Create an account and confirm your email address to obtain a key. The Authentication documentation covers the full details, including the deprecated api_key query parameter.

Once you have both values, send a GET request to the fast_search path with the search string and the Authorization header. The request examples below show the same call in several languages so you can adapt it to your stack.

Request example

The canonical request uses country_code=us and search=pizza+in+new+york. The search value is URL-encoded, with spaces represented as +. The Authorization header carries the Bearer token.

Use the supplied request modules as the exact contract for each language. They are not regenerated here; refer to the module IDs listed in the structured fields.

Response example

A successful response is a JSON payload with structured results. The supplied response module shows the shape: an organic array of result objects, a status field, a top_stories array and a url field. Each organic item includes description, extensions, link, rank and title.

When reading the response, treat rank as the position within the returned organic list and link as the destination URL. The extensions array is present even when empty. The status field indicates completion, and the url field records the search URL associated with the response.

Each successful API call costs 10 API credits.

API key

Every call must carry your private API key as a Bearer token in the Authorization header; the api_key parameter is a required string. Without a valid key the request is not authenticated.

To obtain a key, create an account and confirm your email address. The Authentication documentation explains the full process, including the deprecated api_key query parameter.

Page number

The page parameter is an integer with a default of 1. It selects which page of results to extract. Use page=2 to jump to the second page. Pagination changes which results are returned, not the response shape.

Geolocation

The country_code parameter localizes results to a chosen country. Use ISO 3166-1 alpha-2 codes such as us, fr or de. The default is us. A full list of supported country codes is available in the country codes documentation.

The table below is a partial reference from the supplied documentation. It shows a few example codes and country names; the ellipsis row indicates that the full list is longer.

Tag

The tag parameter attaches a custom string identifier to a request. The value is returned with the response headers. It is optional and has no effect on scraping behavior. Use it to correlate a request with its response, not to filter or change results.

Credit cost for your requests

Each successful Fast Search API request consumes 10 API credits. {{OWNER_PLAN_CREDIT_ALLOWANCE}} Budget accordingly when you plan batch or repeated searches.

Country code reference (partial)
country_codeCountry Name
brBrazil
inIndia
mxMexico
......
uaUkraine
usUnited States
gbUnited Kingdom

Partial reference; the full supported list is in the country codes documentation.

Frequently asked questions

Which parameters are required for a Fast Search API request?

api_key and search are required. api_key is a string sent as a Bearer token in the Authorization header. search is the text you would put in a search bar and must be URL-encoded.

Why should the search term be URL-encoded?

Special characters such as :, & or + can break the query string if they are not encoded. URL-encoding keeps the search value intact when it is sent as a query parameter.

What happens if I omit country_code?

The default is us. Results are localized to the chosen country when you provide an ISO 3166-1 alpha-2 code such as fr or de.

Does the tag parameter change search results?

No. tag is an optional custom identifier returned with the response headers. It has no effect on scraping behavior.

How many API credits does a Fast Search API request cost?

Each successful API call costs 10 API credits. {{OWNER_PLAN_CREDIT_ALLOWANCE}}

curl "{{APP_BASE_URL}}/api/v1/fast_search?country_code=us&search=pizza+in+new+york" \
     -H "Authorization: Bearer YOUR-API-KEY"
curl "{{APP_BASE_URL}}/api/v1/fast_search?search=pizza" \
     -H "Authorization: Bearer YOUR-API-KEY"
curl "{{APP_BASE_URL}}/api/v1/fast_search?search=YOUR-SEARCH-STRING" \
     -H "Authorization: Bearer YOUR-API-KEY"
curl "{{APP_BASE_URL}}/api/v1/fast_search?page=2&search=pizza+in+new+york" \
     -H "Authorization: Bearer YOUR-API-KEY"
curl "{{APP_BASE_URL}}/api/v1/fast_search?country_code=fr&search=pizza+%C3%A0+paris" \
     -H "Authorization: Bearer YOUR-API-KEY"
curl "{{APP_BASE_URL}}/api/v1/fast_search?search=pizza&tag=your+text" \
     -H "Authorization: Bearer YOUR-API-KEY"