Google's Custom Search JSON API shuts down on January 1, 2027. It is already closed to new customers. If your application depends on it, you need a replacement before that date. Google confirms the deadline in its API documentation.
Context.dev's web search API is an alternative for teams that need ranked web results and the content behind them. One request can return titles, URLs, descriptions, and page Markdown. For agents that only need evidence relevant to a question, you can request Highlights instead.
The endpoint change is the easy part. The work is checking what your app expects from Google: domain restrictions, result fields, pagination, and the snippets your model has quietly learned to rely on. This guide walks through those decisions and a first request you can run today.
What is replacing Google Custom Search JSON API?
There is no single replacement that fits every Custom Search application. Start with what your product actually does.
| Your application needs | Replacement to evaluate | What to check first |
|---|---|---|
| Search across a defined set of websites | Google's suggested Vertex AI Search path | Google's guidance describes searching up to 50 domains. Check your coverage and setup requirements. |
| Open web discovery for an AI agent or research tool | Context.dev web search | Relevance, domain filters, source URLs, and whether you need snippets, Highlights, or Markdown. |
| Search and full page retrieval through Firecrawl | Firecrawl search | Its search and scraping options against the queries and pages your application uses. |
| Google result page features for SEO reporting | A provider that explicitly supports the SERP features you need | Result locations, ranking behavior, and fields beyond ordinary web links. |
Google also directs teams that need full web search to an interest form. Treat that as a separate evaluation: confirm access and suitability before putting it on your migration schedule. See Google's current replacement guidance.
Firecrawl covered this migration in its October 23, 2026 article, including search with full page Markdown. That is a useful capability. The decision for your app is how much of each page it needs, and what happens when a page cannot be read.
Why use Context.dev as a Google Search JSON API alternative?
Context.dev lets you choose the amount of source content returned with a search. You can keep a conventional results list, retrieve the pages as Markdown, or ask for relevant passages through Highlights. Those options are documented in our Search guide and result content guide.
Consider an agent answering, “Does this API support webhook retries?” A title and description may help it find the documentation. The retry section provides evidence for the answer. The entire documentation page might also include navigation, unrelated examples, and a long authentication guide.
All three outputs have a place:
- Titles, URLs, and descriptions work for discovery, search interfaces, and deciding which sources to read next.
- Highlights provide passages relevant to the query when an agent needs focused evidence.
- Markdown provides broader page content when the task needs context, multiple sections, or material for a retrieval pipeline.
Start with the smallest output that answers the question. Read more when the evidence is incomplete. That keeps your retrieval choices tied to the task instead of sending every page into every prompt.
How to migrate from Google Custom Search to Context.dev
1. Record the Google features your app uses
Before replacing the request, collect a sample of real queries and the parameters sent with them. Include searches that return nothing, searches restricted to one domain, and searches in your supported languages.
Check the response consumers too. A results component might only read title, link, and snippet. An agent may use those fields plus page text from a separate fetch. Another job may depend on Google's pagination metadata or image search.
Those are different migrations. A successful HTTP response only proves that the new request worked.
2. Run a search with page Markdown
Create a Context.dev API key and set CONTEXT_DEV_API_KEY in your terminal environment. This request asks for five results and enables inline page retrieval:
curl --fail-with-body https://api.context.dev/v1/web/search \
-H "Authorization: Bearer $CONTEXT_DEV_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"query": "webhook retry documentation",
"numResults": 5,
"markdownOptions": {
"enabled": true
}
}'The response contains a results array. Each result has a title, url, and description. When page retrieval succeeds, its Markdown is available at result.markdown.markdown; check result.markdown.code for SUCCESS before using it. The Search API reference documents the full response.
Search success and page retrieval success are separate. A URL can be a useful search result even if its page cannot be retrieved. Keep the URL and description available, and decide whether your task can proceed without the page text.
3. Map the fields your application already reads
The common request and response fields map as follows. This is a migration reference, not a claim that the APIs behave identically.
| Google Custom Search field or setting | Context.dev equivalent or migration action |
|---|---|
q | query |
num | numResults; request between 1 and 100 results, with fewer possible |
| API key in the request URL | Authorization: Bearer header |
cx search engine ID | No engine ID required; configure any needed domain restrictions explicitly |
items | results |
items[].title | results[].title |
items[].link | results[].url |
items[].snippet | results[].description; wording and selection can differ |
| Engine site restrictions | Review includeDomains and excludeDomains |
| Language and location settings | Review languages and country |
| Date restrictions | Review supported freshness windows; do not copy Google values unchanged |
start and queries.nextPage | Redesign pagination; the documented Context.dev search request has no offset parameter |
| Image search and image-specific fields | Evaluate separately; this guide covers web results |
For a consumer that only needs the three basic display fields, a small adapter can preserve its existing shape:
const items = search.results.map((result) => ({
title: result.title,
link: result.url,
snippet: result.description,
}));Here, search is the parsed Context.dev response. Keep any page Markdown alongside the result for downstream retrieval. Do not silently put full page text into a field your application expects to be a short snippet.
Consult the filter documentation before translating domain, language, country, or recency settings. Matching field names is not enough to establish equivalent search behavior.
4. Use Highlights when you need a specific answer
For a focused research question, replace the Markdown option with Highlights:
curl --fail-with-body https://api.context.dev/v1/web/search \
-H "Authorization: Bearer $CONTEXT_DEV_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"query": "Stripe webhook automatic retry duration",
"numResults": 5,
"includeDomains": ["docs.stripe.com"],
"highlightsOptions": {
"enabled": true,
"maxCharacters": 2000
}
}'Successful passages are returned in result.highlights.highlights. Inspect result.highlights.code, and preserve the source URL with the passages so your application can cite the evidence.
This is also worth measuring in an existing agent. In our freecode customer story, replaying real coding sessions with Context Search and Highlights produced 8.9% lower modeled combined LLM and retrieval costs. That result belongs to freecode's workload and pricing assumptions. Use your own sessions to find out whether the same approach helps your application.
5. Test the complete task before switching traffic
Run your saved queries through the old and new integrations while the Google API is still available. Compare what the user receives, including the final answer if a model sits downstream.
| Measure | Practical check |
|---|---|
| Source relevance | Are the pages useful for the original question? |
| Domain restrictions | Are results inside the intended scope? |
| Evidence quality | Can the retrieved text support the answer and its citations? |
| Page retrieval failures | Does the app handle missing Markdown or Highlights without pretending it read the page? |
| Latency | How long until the application has usable evidence, including page reads? |
| Total task cost | Count search, retrieval, retries, and model input together. |
| Empty and partial results | Does the app recover or explain what is missing? |
Set acceptance criteria before you review the output. For example, a documentation assistant may require an official source and a passage that directly supports its answer. A discovery interface may care more about useful coverage across several domains.
If you opt into partial results at a deadline, inspect the response's partial flag. Keep request IDs for troubleshooting. Roll out the replacement to a small share of traffic, watch failure rates, and leave time to fix gaps before January 1.
How should you compare replacement costs?
Compare the cost of a completed task, not just a search request. A cheap results list can become expensive if every result triggers another page fetch, several retries, and a large model prompt.
Use the same queries, result counts, and content settings for each candidate. Record billed usage and the amount of useful evidence returned. Check Context.dev's current pricing and credit documentation for the options you enable, including page retrieval and Highlights.
For some applications, plain search results are enough. For others, returning page content in the search call removes a separate retrieval step. Measure both against the task your users expect to finish.
FAQs
When does Google Custom Search JSON API shut down?
Google lists January 1, 2027 as the service discontinuation date. Existing customers must transition before then, and the API is already closed to new customers. The deadline applies to Custom Search JSON API; it does not mean every Google search product is shutting down.
Is Context.dev a drop-in replacement for Google Custom Search?
No. Context.dev supports web search, but its authentication, request parameters, and response structure differ. You can map titles, URLs, and descriptions into an existing results interface. Pagination, engine configuration, image search, and other Google-specific behavior need separate review.
Can I get search results and full page Markdown in one API call?
Yes. Set markdownOptions.enabled to true on a Context.dev web search request. Successfully retrieved page text is returned with each result. Check the per-result status because a successful search does not guarantee every page can be read.
Does Context.dev return the same rankings as Google Custom Search?
Do not assume identical rankings. Evaluate relevance with representative queries from your application. If your product specifically measures Google rankings or needs particular Google result page features, verify those requirements separately before choosing a replacement.
Should an AI agent use Markdown or Highlights?
Use Markdown when the task needs broad page context, multiple sections, or content for later retrieval. Use Highlights when it needs passages relevant to a specific question. Keep source URLs in either case, and retrieve more content when the available evidence is insufficient.
Start with one query your app already depends on
Choose a production query, run it through Context.dev web search, and compare the evidence with what your application uses today. Then work through the field mapping and failure cases above.
Get an API key and follow the Search quickstart. If your team connects tools through MCP, our Context.dev MCP setup guide covers that path too.