Mantenha tudo organizado com as coleções
Salve e categorize o conteúdo com base nas suas preferências.
Este documento ajudará você a se familiarizar com a API Custom Search JSON e como ela é usada.
Antes de começar
Criar Mecanismo de Pesquisa Programável
Ao chamar o usuário da API, o usuário emite solicitações para uma instância atual do Mecanismo de Pesquisa Programável.
Portanto, antes de usar a API, você precisa criar uma no Painel de controle. Siga o tutorial para saber mais sobre as diferentes opções de configuração.
Depois da criação, você pode encontrar o ID do mecanismo de pesquisa na seção Básico da página Visão geral. Esse é o parâmetro cx usado pela API.
Identifique seu aplicativo para o Google com uma chave de API
A API Custom Search JSON requer o uso de uma chave de API. Uma chave de API é uma maneira de identificar seu cliente para o Google.
Quando você tem uma chave de API, seu aplicativo pode adicionar o parâmetro de consulta key=yourAPIKey a todos os URLs das solicitações. É seguro incorporar a chave de API a URLs, sem precisar de codificação.
Perspectiva geral sobre APIs
Operações de API
Há apenas um método de chamada na API JSON da Pesquisa personalizada:
Retorna os resultados da pesquisa solicitados de um Mecanismo de Pesquisa Programável.
GET
Modelo de dados de API
O resultado de uma consulta de pesquisa à API JSON da Pesquisa personalizada é um objeto JSON que inclui três tipos de dados:
Metadados que descrevem a pesquisa solicitada (e possivelmente solicitações de pesquisas relacionadas)
Metadados que descrevem o Mecanismo de Pesquisa Programável
Resultados da pesquisa
Consulte a seção "Dados de resposta" de Como usar REST para mais detalhes.
O modelo de dados é baseado na Especificação do OpenSearch 1.1. Além das propriedades padrão do OpenSearch, a API JSON da Pesquisa personalizada define duas propriedades e duas funções de consulta personalizadas:
Propriedades personalizadas
cx: o identificador do Mecanismo de Pesquisa Programável.
safe: uma descrição do nível de segurança da pesquisa para filtrar os resultados retornados.
Papéis de consulta personalizados
nextPage: um papel que indica que a consulta pode ser usada para
acessar a próxima página lógica de resultados, se houver.
previousPage: um papel que indica que a consulta pode ser usada
para acessar a página lógica anterior de resultados, se houver.
[[["Fácil de entender","easyToUnderstand","thumb-up"],["Meu problema foi resolvido","solvedMyProblem","thumb-up"],["Outro","otherUp","thumb-up"]],[["Não contém as informações de que eu preciso","missingTheInformationINeed","thumb-down"],["Muito complicado / etapas demais","tooComplicatedTooManySteps","thumb-down"],["Desatualizado","outOfDate","thumb-down"],["Problema na tradução","translationIssue","thumb-down"],["Problema com as amostras / o código","samplesCodeIssue","thumb-down"],["Outro","otherDown","thumb-down"]],["Última atualização 2025-08-31 UTC."],[[["\u003cp\u003eThis guide introduces the Custom Search JSON API and provides instructions for its use.\u003c/p\u003e\n"],["\u003cp\u003eBefore using the API, you need to create a Programmable Search Engine and obtain an API key.\u003c/p\u003e\n"],["\u003cp\u003eThe API allows you to retrieve search results from your Programmable Search Engine using a single \u003ccode\u003elist\u003c/code\u003e operation.\u003c/p\u003e\n"],["\u003cp\u003eThe API returns results in JSON format containing search metadata, engine details, and the search results themselves.\u003c/p\u003e\n"],["\u003cp\u003eYou can experiment with the API using the provided "Try this API" tool or learn more through detailed documentation and examples.\u003c/p\u003e\n"]]],[],null,["# Custom Search JSON API: Introduction\n\nThis document will help you to get familiar with Custom Search JSON API and its usage.\n\nBefore you start\n----------------\n\n### Create Programmable Search Engine\n\nBy calling the API user issues requests against an existing instance of\nProgrammable Search Engine.\nTherefore, before using the API, you need to create one in the\n[Control Panel](https://programmablesearchengine.google.com/controlpanel/create)\n. Follow the [tutorial](/custom-search/docs/tutorial/creatingcse)\nto learn more about different configuration options.\nOnce it is created, you can find the **Search Engine ID** in the **Overview**\npage's **Basic** section. This is the `cx` parameter used by the API.\n\n### Identify your application to Google with API key\n\nCustom Search JSON API requires the use of an API key. An API key is a way to identify your client to Google.\n\n- [Programmable Search Engine](https://cse.google.com/) (free edition) users: Get a Key\n\nAfter you have an API key, your application can append the query parameter\n`key=yourAPIKey` to all request URLs. The API key is safe for embedding in URLs,\nit doesn't need any encoding.\n\nAPI overview\n------------\n\n### API operations\n\nThere is only one method to invoke in the Custom Search JSON API:\n\n| Operation | Description | REST HTTP mapping |\n|------------------------------------------------------|-------------------------------------------------------------------------|-------------------|\n| [list](/custom-search/v1/reference/rest/v1/cse/list) | Returns the requested search results from a Programmable Search Engine. | `GET` |\n\n### API data model\n\nThe result of a search query to the Custom Search JSON API is a JSON object that includes three types of data:\n\n- Metadata describing the requested search (and, possibly, related search requests)\n- Metadata describing the Programmable Search Engine\n- Search results\n\nSee the Response data section of [Using REST](/custom-search/v1/using_rest#response_data) for more details.\n\nThe data model is based on the OpenSearch 1.1 Specification. In addition to the standard OpenSearch properties, the Custom Search JSON API defines two custom properties and two custom query roles:\n\n- Custom properties\n - `cx`: The identifier of the Programmable Search Engine.\n - `safe`: A description of the safe search level for filtering the returned results.\n- Custom query roles\n - `nextPage`: A role that indicates the query can be used to access the next logical page of results, if any.\n - `previousPage`: A role that indicates the query can be used to access the previous logical page of results, if any.\n\nTry it\n------\n\nTo play around and see what the API can do, without writing any code, visit the\n[\"Try this API\" tool](/custom-search/v1/reference/rest/v1/cse/list?apix=true).\n\nFor a full description of parameters visit the\n[cse.list reference](/custom-search/v1/reference/rest/v1/cse/list).\n\nTo learn how to use the API via HTTP requests, continue to\n[Using REST](/custom-search/v1/using_rest)."]]
