To create a Google Programmable Search Engine, open Google’s Programmable Search Engine Control Panel, name the engine, specify the sites or URL patterns it should search, and click Create. You can then publish Google’s hosted search page, embed a search box on your site, or (where eligible) request results through an API. This guide covers setup, configuration, embedding, API limits, troubleshooting, and current availability.
What a Google Programmable Search Engine does
A Programmable Search Engine (formerly known as Custom Search) lets you build a search experience focused on selected websites, pages, or URL patterns. The sites do not have to be yours. You can create a private-topic search, a documentation search, a site-wide search box, or an engine that searches the broader web with Google’s inclusion rules.
Google provides three practical delivery methods:
- Hosted search page: Google hosts a page where visitors enter queries.
- Search Element: JavaScript places a search box and results interface in your webpage.
- Programmatic results: An API returns JSON for your own interface or application, subject to current customer eligibility.
Create the engine in the Control Panel
- Sign in. Open the Programmable Search Engine Control Panel with a Google Account.
- Name the engine. In Name your search engine, enter a descriptive name such as “Company Documentation Search.” Google says you can change this name later.
- Choose what to search. In What to search?, add whole-site URLs, individual page URLs, or URL patterns. For example, you might add
docs.example.com/*for documentation or a specific path such asexample.com/support/*. You may add sites you do not own. - Create it. Select Create. Google’s tutorial describes the resulting basic engine as ready to use.
- Open the control panel. Continue in the panel to adjust ranking, refinements, appearance, image search, promotions, autocomplete, analytics, and other settings.
How to choose URL entries
- Use a whole domain when every section is relevant.
- Use a path pattern when only a product, language, or documentation area should appear.
- Add individual pages for a small, curated collection.
- Review trailing slashes, subdomains, and URL patterns carefully; a pattern that is too broad can include navigation, account pages, or duplicate content.
Configure ranking, appearance, and search behavior
The Control Panel is where the useful distinctions between a basic engine and a production search experience are made.
Refinements
Create labels that let users narrow results into categories such as “API,” “Guides,” or “Support.” Refinements are especially helpful when one engine covers several product areas.
#1 Best Overall
Result ordering
Use ranking controls to emphasize specific pages or sources. Treat manual boosts as editorial rules: a page that is permanently promoted can mask newer or more relevant material.
Autocomplete and promotions
Autocomplete can suggest common queries as users type. Promotions place selected results in a prominent area for defined searches. Keep suggestions and promotions current, and remove entries for retired products or campaigns.
Styling and branding
Adjust colors, fonts, layout, and the visible engine name so the search interface fits your site. Test the result page on narrow screens as well as desktop widths.
Image search and analytics
Google documents image-search settings and analytics integrations for Programmable Search Engines. Enable only the search modes you can maintain, and check that analytics collection follows your site’s privacy requirements.
Structured data and monetization
Google documents structured-data features and says a Programmable Search Engine can be monetized with Google AdSense. Eligibility, approval, and revenue terms can change, so confirm the current AdSense requirements before designing a business model around search ads.
Publish a search box on your website
Use Google’s hosted page
The fastest option is to publish the hosted search homepage generated for your engine and link to it from your navigation, help center, or footer. This requires no site JavaScript, but the page has less control over surrounding layout.
Embed the Search Element
For an on-site experience, choose the Search Element option in the Control Panel and copy the generated code into the page where the search interface should appear. The generated snippet identifies your engine and renders the query box and results client-side.
- Open the engine in the Control Panel.
- Choose the option to get or embed the search element.
- Copy the generated script and container markup.
- Paste it into the page template or component where search belongs.
- Publish and test a normal query, an empty query, a query with punctuation, and a query that should return no results.
Keep the snippet’s engine identifier intact. If results appear from the wrong collection, the most common cause is using a snippet generated for a different engine.
Recommended Free Tools
Can you search the entire web?
Google offers an entire-web setting, but it is not identical to Google’s main Web Search. Google notes that this mode emphasizes the sites included in your engine and may return only a subset of Google’s index when more than ten sites are included. Some standard Google Web Search features are absent. For a focused product, research, or documentation engine, explicit site and path entries usually produce more predictable results.
Rank #3
- Google search engine.
Use the API for programmatic results
The traditional Custom Search JSON API route requires a configured engine, its search-engine ID (cx), an API key, and a request containing q. A typical request conceptually includes these parameters:
key: your Google API keycx: the Programmable Search Engine IDq: the user’s query
Google’s current API overview says the Custom Search JSON API is not available to new customers. Existing customers have until January 1, 2027 to transition, and Google points new use cases toward Vertex AI Search. Verify availability in your Google account before writing a new integration around this API.
Published limits and pricing figures
Google’s API overview lists 100 free queries per day and, for existing Custom Search JSON API customers, $5 per 1,000 additional queries up to 10,000 queries per day. Google’s Programmable Search Engine version comparison also lists $5 per 1,000 queries for its paid API and JSON API entries. These figures describe Google’s published offerings; they do not override the newer closure notice for new API customers.
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Clear out junk files and repair common Windows errorsFree Scan →| Delivery or offering | Audience or availability | Published price or limit |
|---|---|---|
| Standard Search Element | General users | Free |
| Non-profit Search Element | Eligible non-profits | Free |
| Paid API | Listed in Google’s comparison table; confirm current eligibility | $5 per 1,000 queries |
| Custom Search JSON API | Existing customers; closed to new customers | 100 free queries/day; then $5 per 1,000, up to 10,000/day |
Because Google’s documents describe both a comparison table and a newer closure notice, treat API access as an eligibility question rather than a guaranteed purchase option.
Security, privacy, and operational checks
- Do not put an API key in browser JavaScript. Proxy API calls through your server and restrict the key in Google Cloud.
- Validate and rate-limit user queries before forwarding them.
- Decide whether search terms may contain personal or confidential information, and document retention and logging rules.
- Test indexing after adding or removing URL patterns; configuration changes do not guarantee that every page appears immediately.
- Provide a useful no-results state with links to navigation, help, or a contact route.
Troubleshooting common problems
The engine returns no results
Check that the URL or pattern is correct, reachable without authentication, and entered under the intended engine. Narrow patterns can accidentally exclude every page. Test a known page title and a broad term.
Results include unwanted sections
Replace a domain-wide entry with a path pattern, remove overlapping entries, and review ranking or promotion rules. A broad entire-web configuration can also introduce results outside your intended collection.
The search box is blank
Confirm that the generated script and container were copied completely, that the page permits the script under its Content Security Policy, and that no JavaScript error stops execution. Check the browser console and test the unmodified generated snippet on a blank page.
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →The API key or cx fails
Verify the key, engine ID, enabled API, restrictions, billing configuration, and daily quota. If you are a new customer, the failure may reflect Google’s policy that the Custom Search JSON API is closed to new customers rather than a malformed request.
Best Value
Results look stale
Search engines depend on crawling and indexing. Confirm that the source page is publicly accessible, request recrawling through the site’s normal search-visibility workflow, and avoid relying on a just-published page for time-critical results.
Or skip the browser setup
If your project needs screenshots of search results, documentation, or generated pages rather than a search index itself, ScreenshotNeo provides a one-request website screenshot API and MCP server. It accepts consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each cleanup step can be disabled. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers identify the page verdict and billing status.
Use the API documentation at https://screenshotneo.com/docs/ for all options. A cURL request is:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpPython:
import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)Node.js:
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);ScreenshotNeo also supports full-page and element captures, device presets, custom viewports, retina scale, PDF output, custom CSS and JavaScript, waits, request blocking, headers and cookies, geolocation, caching, signed links, asynchronous webhooks, bulk capture of up to 100 URLs per call, and an MCP server with take_screenshot, get_page_info, and capture_pdf for AI agents. The Free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000. Create a free ScreenshotNeo account.
FAQ
Can I add a website I do not own?
Yes. Google’s creation instructions allow whole-site URLs, individual pages, and URL patterns that do not have to be owned by you, provided the content is publicly searchable.
Can I rename an engine later?
Yes. Google states that the name entered during creation can be changed later in the Control Panel.
Is the JSON API a safe choice for a new project?
Not without confirming eligibility. Google says the Custom Search JSON API is closed to new customers and gives existing customers until January 1, 2027 to transition.
Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Repair Windows errors before they cause bigger problems3Fix the driver behind crashes, sound loss and screen glitchesQuick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
