Skip to main content
Whether you’re evaluating the API for the first time or running into an unexpected behavior, this page collects the questions developers ask most often. Each answer links to the relevant guide for deeper reading.
The Custom Search JSON API lets you embed Google-quality search into your own applications by sending HTTP GET requests to https://www.googleapis.com/customsearch/v1. You provide a search query (q), your API key (key), and a Search Engine ID (cx), and Google returns up to 10 ranked results per request as structured JSON.Use it to power site search, research tools, content aggregators, or any feature where users need to find information across the web or within a specific set of sites.
The Custom Search JSON API is distinct from the older Custom Search Site Search product and the deprecated Google Site Search API. If you see references to either of those, they no longer accept new sign-ups.
You create an API key in the Google Cloud Console:
1

Open the Cloud Console

Go to console.cloud.google.com and sign in with your Google account.
2

Create or select a project

Click the project picker at the top of the page and either select an existing project or choose New Project.
3

Enable the API

Navigate to APIs & Services → Library, search for Custom Search API, and click Enable.
4

Create credentials

Go to APIs & Services → Credentials, click Create Credentials, and select API key. Copy the key that appears.
5

Restrict the key (recommended)

Click Edit API key and add an API restriction to limit the key to the Custom Search API only. Optionally add HTTP referrer or IP restrictions for production use.
Pass your key as the key query parameter on every request:
Never embed your API key directly in client-side JavaScript or public repositories. Use environment variables or a server-side proxy to keep it private.
A Search Engine ID (also called a cx or Programmable Search Engine ID) identifies the specific search engine configuration you want to use. Every search request must include one.You create and manage Search Engine IDs at programmablesearchengine.google.com:
  1. Click Add to create a new engine.
  2. Choose whether to search the entire web or limit results to specific sites.
  3. Copy the Search engine ID from the Overview or Setup panel — it looks like 017576662512468239146:omuauf_lfve.
Your cx value travels as a query parameter:
One Google account can own up to 100 Programmable Search Engines. Each engine can have its own site scope, SafeSearch setting, and ranking configuration.
Yes. When you create a Programmable Search Engine, enable the Search the entire web toggle in the Setup panel. With this setting active, your engine searches all publicly indexed pages on Google — not just the sites you specified.You can still add included sites to boost results from those domains, or use excluded sites to suppress specific domains, while still covering the full web.If you prefer to scope results programmatically, use the siteSearch parameter at request time:
Setting siteSearchFilter=i includes only pages from nature.com; setting it to e excludes them.
Each request returns up to 10 results. Set the exact number with the num parameter (integer from 1 to 10):
To retrieve results beyond the first 10, use the start parameter. start accepts values from 1 to 91, meaning you can access up to 100 results total across multiple requests (pages 1–10):
Each paginated call counts as a separate query against your daily quota. There is no way to retrieve more than 100 results for a single query regardless of pagination.
The free tier gives you 100 queries per day at no cost. This resets at midnight Pacific Time.If you need more than 100 queries per day, you can enable billing on your Google Cloud project and purchase additional queries at $5 per 1,000 queries, up to a maximum of 10,000 queries per day per project. If your needs exceed 10,000 queries per day, contact Google Cloud sales to discuss an enterprise arrangement.
You can monitor how many queries you’ve used today in the Google Cloud Console under APIs & Services → Dashboard → Custom Search API → Metrics.
See the Rate Limits and Quotas page for a full tier comparison and best practices for staying within your limits.
Add searchType=image to your request. This tells the API to return image results instead of web page results:
Image results include an image object on each item with the following fields:You can further refine image results with:
  • imgSize — icon, small, medium, large, xlarge, xxlarge, huge
  • imgType — clipart, face, lineart, stock, photo, animated
  • imgColorType — color, gray, mono, trans
  • fileType — e.g., jpg, png, gif
Yes. You have two complementary approaches:Option 1 — Use siteSearch at request time (flexible)Pass the domain you want to restrict to via the siteSearch parameter and set siteSearchFilter=i (include):
Option 2 — Scope the Search Engine to specific sites (permanent)In the Programmable Search Engine control panel, add one or more sites under Sites to search. Results will only come from those domains regardless of what q you send.Use Option 1 when the target domain varies per query. Use Option 2 when you always want results from the same fixed set of sites.
You can include up to 20 domains in a single siteSearch parameter by repeating the parameter or using comma-separated values, depending on your engine configuration.
A 403 response means the API refused your request. The three most common causes are:Check the error.errors[0].reason field in the JSON response body — it identifies the exact cause:
See the Troubleshooting guide for step-by-step resolution instructions.
Follow these steps to raise your daily query limit above the free 100 queries/day:
1

Enable billing

Go to Google Cloud Console → Billing and link a payment method to your project. This automatically raises your limit to 10,000 queries/day.
2

Verify the new limit

Navigate to APIs & Services → Custom Search API → Quotas. You should see the Queries per day limit updated to 10,000.
3

Request a higher limit (if needed)

If 10,000 queries/day is still insufficient, click Edit quotas on the Quotas page and submit a quota increase request. Google typically reviews requests within 2 business days.
Billing is per query over 100/day: $5 per 1,000 queries. You are charged only for actual usage, not for the headroom you request. There is no minimum spend.
The Custom Search JSON API does not have dedicated searchType values for video or news (only image is supported as a searchType). However, you can approximate these:
  • News — Add dateRestrict=d7 to surface recently published content, combine with siteSearch targeting news domains (e.g., reuters.com, bbc.com), or use sort=date to rank by recency.
  • Video — Use siteSearch=youtube.com&siteSearchFilter=i to restrict results to YouTube, or add filetype:mp4 inside the q parameter.
If you need a purpose-built video or news search experience, consider the YouTube Data API or Google News RSS feeds as complementary solutions.
A successful response contains the following top-level fields:Each object in items[] includes: