Entrar Teste grátis
Deutsch English Español Français Italiano Português 日本語
Teste grátis Entrar
  • Primeiros passos
  • Início rápido
  • Informações
  • Limites de chamadas
  • Versões do Google
  • Lista de versões
  • SERPS
  • Requisições à Pesquisa Google
  • Requisições do Google Maps
  • IDs das requisições
  • Recuperar SERPs
  • URL de callback
  • Status de processamento das SERPs
  • Histórico de requisições
  • Faturamento
  • Saldo restante
  • Formas de pagamento

Documentação da API do Semscraper

Início rápido

Três passos para obter sua primeira SERP do Google em JSON.

  1. Crie sua conta: 1.000 SERPs grátis, sem cartão de crédito. Depois copie sua chave no menu Chaves de API da sua conta. Ela é enviada no cabeçalho Authorization: Bearer de cada chamada. Criar uma conta grátis
  2. Envie suas palavras-chave com POST /v1/serp, até 1.000 por chamada. A resposta retorna o identificador e o custo de cada SERP: é o único momento em que você é cobrado.
    Enviar uma palavra-chave
    curl -X POST https://api.semscraper.com/v1/serp \
  -H "Authorization: Bearer SUA_CHAVE_API" \
  -H "Content-Type: application/json" \
  -d '[{"search_engine": "google_search", "keyword": "receita de panqueca", "device": "desktop", "location": "br", "language": "pt", "depth": 1}]'
  3. Recupere o resultado com GET /v1/serp e o identificador recebido: substitua SERP_ID pelo valor do campo data[0].id retornado na etapa anterior.A coleta é assíncrona: enquanto o status for pending ou processing, tente de novo um pouco mais tarde. A recuperação nunca é cobrada.
    Recuperar a SERP
    curl "https://api.semscraper.com/v1/serp?ids=SERP_ID&output=json" \
  -H "Authorization: Bearer SUA_CHAVE_API"

Para ser avisado sem consultar a API, adicione um callback_url às suas requisições. Para centenas de milhares de palavras-chave, veja a API Bulk SERP.

Informações

Limites de chamadas

Limitar o número de chamadas à API
GET : 500 chamadas por minuto
POST : 500 chamadas por minuto

Versões do Google

Lista de versões

Obtenha os parâmetros location e language necessários para recuperar as SERPs do Google.
get
https://api.semscraper.com/v1/serp/google/location
Autorizações : Bearer {api_key}
  • Requisição
  • Resposta bem-sucedida
Status: 200 OK
{
    "status": "success",
    "request_ms": 17,
    "count": 372,
    "data": [
        {
            "location": "en",
            "language": "en",
            "host": "google.com",
            "name": "World Wide Web"
        },
        {
            "location": "fr",
            "language": "fr",
            "host": "google.fr",
            "name": "France"
        }
}

SERPs

Requisições à Pesquisa Google

Criação de requisições de SERPs da Pesquisa Google
Os dados devem ser enviados em um array JSON. Cada elemento deve conter os seguintes campos.
Limite
O array JSON pode conter 1000 elementos, ou seja, você pode criar 1000 scrapings de SERPs em uma única chamada.
post
https://api.semscraper.com/v1/serp
Autorizações : Bearer {api_key}
Parâmetros
search_engine
Obrigatório
string
Escolha do mecanismo de busca:
Pesquisa Google (valor: google_search)
keyword
Obrigatório
string
Palavras-chave a pesquisar no mecanismo de busca
device
Obrigatório
string
Escolha do dispositivo:
Computador (valor: desktop)
Celular (valor: mobile)
depth
Obrigatório
integer
Profundidade de páginas: recuperamos as SERPs do Google com paginação. Este parâmetro deve estar entre 1 (cerca de 10 resultados) e 10 (cerca de 100 resultados).
location
Obrigatório
string
Código de localização do mecanismo de busca
language
Obrigatório
string
Idioma do mecanismo de busca
geolocation
string
Geolocaliza uma SERP do Google. Informe a cidade, a região e o país separados por vírgulas (ex.: Nice, Alpes-Maritimes, France) ou uma posição GPS latitude,longitude em graus decimais (ex.: 43.7102,7.2620).
priority
integer
Permite priorizar suas requisições, que são processadas em ordem decrescente de prioridade. Valor entre 1 (baixa) e 10 (alta).
callback_url
string
Permite informar uma URL para a qual enviaremos os resultados da palavra-chave assim que ela for processada.
Tipos de blocos de resultados
Valores possíveis do campo type. Um bloco só aparece na resposta se o Google o exibir para a palavra-chave solicitada.
Resultados e anúncios
organic
Resultado orgânico
Resultado orgânico padrão da pesquisa.
sitelinks
Sitelinks
Link secundário vinculado a um resultado orgânico.
paid_top
Anúncio no topo
Anúncio pago acima dos resultados orgânicos.
paid_bottom
Anúncio no rodapé
Anúncio pago abaixo dos resultados orgânicos.
Blocos enriquecidos
featured_snippet
Snippet em destaque
Trecho em destaque acima dos resultados orgânicos.
knowledge_graph
Painel de informações
Elemento do painel exibido à direita da SERP.
images
Imagens
Miniatura do bloco de imagens.
videos
Vídeos
Vídeo do bloco de vídeos.
top_stories
Principais notícias
Artigo do bloco Principais notícias.
shopping
Shopping
Produto do carrossel do Google Shopping.
recipes
Receitas
Receita do bloco de receitas.
local_pack
Pacote local
Estabelecimento do pacote local, vindo do Google Maps.
visual_digest
Resumo visual
Elemento do resumo visual gerado pelo Google.
Sugestões e buscas relacionadas
people_also_ask
As pessoas também perguntam
Pergunta do bloco As pessoas também perguntam.
related_searches
Pesquisas relacionadas
Pesquisa relacionada sugerida no fim da página.
find_results_on
Encontre resultados em
Link do bloco Encontre resultados em.
location_sites
Sites de localização
Site listado em um bloco relacionado a uma localização.
AI Overview
ai_overview_citation
Citação
Marca citada no texto gerado pela IA.
ai_overview_citation_source
Fonte da citação
Fonte de uma citação, exibida ao passar o mouse sobre ela.
ai_overview_panel
Painel de fontes
Site listado no painel lateral de fontes.
  • Requisição
  • Resposta bem-sucedida
  • Resposta de erro
Status: 200 OK
{
    "status": "success",
    "request_ms": 40,
    "count": 1,
    "currency": "EUR",
    "total_cost": 0.0003,
    "data": [
        {
            "id": "SERP_ID",
            "status": "pending",
            "keyword": "example keyword",
            "device": "mobile",
            "location": "fr",
            "language": "fr",
            "depth": 1,
            "geolocation": false,
            "priority": 1,
            "callback_url": null,
            "cost": 0.0003,
            "_links": {
                "json": {
                    "href": "/serp?ids=SERP_ID&output=json",
                    "method": "GET",
                    "type": "application/json"
                },
                "html": {
                    "href": "/serp?ids=SERP_ID&output=html",
                    "method": "GET",
                    "type": "application/json"
                }
            }
        }
    ]
}
Status: 400 Bad Request
{
    "error": "Bad Request",
    "message": "DESCRIPTION_OF_ERROR",
    "code": 400
}

Requisições do Google Maps

Criação de requisições de SERPs do Google Maps
Os dados devem ser enviados em um array JSON. Cada elemento deve conter os seguintes campos.
Limite
O array JSON pode conter 1000 elementos, ou seja, você pode criar 1000 scrapings de SERPs em uma única chamada.
post
https://api.semscraper.com/v1/serp
Autorizações : Bearer {api_key}
Parâmetros
search_engine
Obrigatório
string
Escolha do mecanismo de busca:
Google Maps (valor: google_maps)
keyword
Obrigatório
string
Palavras-chave a pesquisar no mecanismo de busca
depth
Obrigatório
integer
Profundidade de páginas: recuperamos as SERPs do Google com paginação. Este parâmetro deve estar entre 1 (cerca de 10 resultados) e 10 (cerca de 100 resultados).
location
Obrigatório
string
Código de localização do mecanismo de busca
language
Obrigatório
string
Idioma do mecanismo de busca
geolocation
string
Geolocaliza uma SERP do Google. Informe a cidade, a região e o país separados por vírgulas (ex.: Nice, Alpes-Maritimes, France) ou uma posição GPS latitude,longitude em graus decimais (ex.: 43.7102,7.2620). Com uma posição GPS, você pode adicionar um nível de zoom opcional (ex.: 43.7102,7.2620,16z).
priority
integer
Permite priorizar suas requisições, que são processadas em ordem decrescente de prioridade. Valor entre 1 (baixa) e 10 (alta).
callback_url
string
Permite informar uma URL para a qual enviaremos os resultados da palavra-chave assim que ela for processada.
  • Requisição
  • Resposta bem-sucedida
  • Resposta de erro
Status: 200 OK
{
    "status": "success",
    "request_ms": 40,
    "count": 1,
    "currency": "EUR",
    "total_cost": 0.0003,
    "data": [
        {
            "id": "SERP_ID",
            "status": "pending",
            "keyword": "example keyword",
            "device": "mobile",
            "location": "fr",
            "language": "fr",
            "depth": 1,
            "geolocation": false,
            "priority": 1,
            "callback_url": null,
            "cost": 0.0003,
            "_links": {
                "json": {
                    "href": "/serp?ids=SERP_ID&output=json",
                    "method": "GET",
                    "type": "application/json"
                },
                "html": {
                    "href": "/serp?ids=SERP_ID&output=html",
                    "method": "GET",
                    "type": "application/json"
                }
            }
        }
    ]
}
Status: 400 Bad Request
{
    "error": "Bad Request",
    "message": "DESCRIPTION_OF_ERROR",
    "code": 400
}

IDs das requisições

Lista dos IDs das SERPs concluídas que você ainda não recuperou.
Este método permite obter os IDs de todas as SERPs já processadas, mas nunca recuperadas. Depois, você pode chamar o método de recuperação de SERPs com esses IDs.
get
https://api.semscraper.com/v1/serp
Autorizações : Bearer {api_key}
  • Requisição
  • Resposta bem-sucedida
Status: 200 OK
{
    "status": "success",
    "request_ms": 40,
    "count": 2,
    "data": [
        {
            "id": "SERP_ID",
            "status": "done",
            "keyword": "example keyword",
            "device": "desktop",
            "location": "fr",
            "language": "fr",
            "depth": 5,
            "geolocation": false,
            "callback_url": "",
            "cost": 0.0011,
            "_links": {
                "json": {
                    "href": "/serp?ids=SERP_ID&output=json",
                    "method": "GET",
                    "type": "application/json"
                },
                "html": {
                    "href": "/serp?ids=SERP_ID&output=html",
                    "method": "GET",
                    "type": "application/json"
                }
            }
        },
        {
            "id": "SERP_ID",
            "status": "done",
            "keyword": "example keyword",
            "device": "mobile",
            "location": "fr",
            "language": "fr",
            "depth": 5,
            "geolocation": false,
            "callback_url": "",
            "cost": 0.0011,
            "_links": {
                "json": {
                    "href": "/serp?ids=SERP_ID&output=json",
                    "method": "GET",
                    "type": "application/json"
                },
                "html": {
                    "href": "/serp?ids=SERP_ID&output=html",
                    "method": "GET",
                    "type": "application/json"
                }
            }
        }
    ]
}

Recuperar SERPs

Recuperar SERPs do Google pelos IDs
Recupere várias SERPs em uma única chamada (em formato JSON ou HTML) informando vários IDs separados por vírgula.
Limite
Você pode informar até 100 IDs, o que permite recuperar 100 SERPs em uma única chamada.
get
https://api.semscraper.com/v1/serp?ids=id1,id2&output=json
Autorizações : Bearer {api_key}
Parâmetros
ids
Obrigatório
string
Lista de IDs separada por vírgulas.
output
Obrigatório
string
Escolha do formato de saída:
JSON (valor: json)
HTML (valor: html)
Formato do resultado
  • Google Search
  • Google Maps
type
string
Tipo de bloco de resultados (orgânico, vídeos, imagens, people_also_ask, local_pack...)
rank_type
integer
Posição do elemento dentro do seu próprio tipo de bloco (por exemplo: 3º resultado orgânico = 3)
rank_serp
integer
Posição absoluta na SERP completa, considerando todos os blocos, de acordo com a posição vertical real na página (em pixels)
page
integer
Número da página da SERP em que o elemento aparece
pixel
integer
Posição vertical do elemento na página, em pixels a partir do topo
domain
string
Domínio da URL
url
string
URL do resultado
title
string
Título exibido do resultado
description
string
Descrição / trecho exibido do resultado
brand
string
Marca citada ou rótulo da fonte, conforme exibido pelo Google. Somente nos blocos ai_overview_citation, ai_overview_citation_source e ai_overview_panel. Em uma citação, a URL muitas vezes vem vazia: nesse caso, a marca é a única informação do elemento.
visible
boolean
Indica se o elemento aparece logo de início no AI Overview (true) ou só depois de expandi-lo (false). Somente nos blocos AI Overview. Sempre false para ai_overview_citation_source, que só aparece ao passar o mouse sobre uma citação.
rating
float
Nota média exibida pelo Google (por exemplo, 4.1). Somente nos blocos organic e local_pack; null quando o resultado não exibe estrelas.
reviews
integer
Número de avaliações por trás da nota. Somente nos blocos organic e local_pack; null quando o resultado não exibe estrelas.
price_range
string
Faixa de preço do estabelecimento, conforme exibida pelo Google (por exemplo, \"20–30 €\"). Somente no bloco local_pack; null quando ausente.
details
array
Informações exibidas abaixo do estabelecimento, na ordem e no idioma do Google: preço, categoria, endereço, horário de funcionamento, serviços… Somente no bloco local_pack. Nem a ordem nem a presença de cada informação são garantidas.
serp_info.ai_overview
object
AI Overview da SERP, no objeto serp_info (e não em results). Contém type, text e complete.
serp_info.ai_overview.type
string
Modo de exibição do AI Overview: sync (presente na página assim que ela carrega), async (gerado pelo Google em tempo real, depois que a página carregou) ou none (sem AI Overview).
serp_info.ai_overview.text
string
Texto gerado pela IA, em texto simples (sem formatação nem links). null quando a SERP não tem AI Overview ou quando não foi possível ler o texto.
serp_info.ai_overview.complete
boolean
True quando o AI Overview já tinha terminado de ser gerado no momento da captura. false quando o texto está ausente ou pode estar incompleto.
rank_type
integer
Posição do elemento dentro do seu próprio tipo de bloco (por exemplo: 3º resultado orgânico = 3)
rank_serp
integer
Posição absoluta na SERP completa, considerando todos os blocos, de acordo com a posição vertical real na página (em pixels)
page
integer
Número da página da SERP em que o elemento aparece
pixel
integer
Posição vertical do elemento na página, em pixels a partir do topo
title
string
Título exibido do resultado
cid
string
Identificador do Google (CID) da ficha do estabelecimento
reviews
integer
Número de avaliações
rating
float
Nota média (em uma escala de 5)
website
string
Site do estabelecimento
type
string
Categoria do estabelecimento (por exemplo: Restaurante)
address
string
Endereço postal
status_label
string
Status de funcionamento (por exemplo: Aberto, Fechado)
status_detail
string
Detalhes do status (por exemplo: horários)
comment
string
Comentário / trecho exibido
images
array
Lista de imagens da ficha
  • Requisição
  • Resposta bem-sucedida
  • Resposta de erro
Status: 200 OK
{
    "status": "success",
    "request_ms": 41,
    "count": 1,
    "data": [
        {
            "id": "SERP_ID",
            "status": "done",
            "keyword": "example keyword",
            "device": "desktop",
            "location": "fr",
            "language": "fr",
            "depth": 1,
            "geolocation": false,
            "priority": 1,
            "callback_url": "",
            "cost": 0.0003,
            "created_at": "2025-09-10T12:32:56Z",
            "scraped_at": "2025-09-10T12:33:02Z",
            "duration_ms": 5403,
            "serp_info": {
                "result_count": 1500000000,
                "ai_overview": {
                    "type": "async",
                    "text": "A keyword is a word or phrase that users type into a search engine to find information...",
                    "complete": true
                }
            },
            "results": [
                {
                    "type": "people_also_ask",
                    "items": [
                        {
                            "rank_type": 1,
                            "rank_serp": 4,
                            "page": 1,
                            "pixel": 806,
                            "domain": "guides.lib.uh.edu",
                            "url": "https://guides.lib.uh.edu/c.php?g\\x3d1249281",
                            "title": "What is a keyword example?",
                            "description": ""
                        },
                        {
                            "rank_type": 2,
                            "rank_serp": 5,
                            "page": 1,
                            "pixel": 858,
                            "domain": "toolsqa.com",
                            "url": "https://toolsqa.com/cucumber/data-driven-testing-using-examples-keyword/",
                            "title": "What is the example keyword used for?",
                            "description": ""
                        },
                        {
                            "rank_type": 3,
                            "rank_serp": 6,
                            "page": 1,
                            "pixel": 911,
                            "domain": "www.editage.com",
                            "url": "https://www.editage.com/insights/how-to-create-keywords-for-a-research-paper",
                            "title": "How do you write keywords examples?",
                            "description": ""
                        },
                        {
                            "rank_type": 4,
                            "rank_serp": 7,
                            "page": 1,
                            "pixel": 964,
                            "domain": "libguides.lvc.edu",
                            "url": "https://libguides.lvc.edu/c.php?g\\x3d1152118\\x26ampp\\x3d8409030",
                            "title": "What is an example of a keyword search?",
                            "description": ""
                        }
                    ]
                },
                {
                    "type": "videos",
                    "items": [
                        {
                            "rank_type": 1,
                            "rank_serp": 1,
                            "page": 1,
                            "pixel": 223,
                            "domain": "www.youtube.com",
                            "url": "https://www.youtube.com/watch?v=H-B5oFJjL8I",
                            "title": "What are Keywords and How to Choose Them? 1.1. SEO ...",
                            "description": ""
                        },
                        {
                            "rank_type": 2,
                            "rank_serp": 2,
                            "page": 1,
                            "pixel": 374,
                            "domain": "www.youtube.com",
                            "url": "https://www.youtube.com/watch?v=TTlEVVB75wo&pp=2AEAkAIB",
                            "title": "What Are Keywords? Everything You Need To Know (and more)",
                            "description": ""
                        },
                        {
                            "rank_type": 3,
                            "rank_serp": 3,
                            "page": 1,
                            "pixel": 526,
                            "domain": "www.youtube.com",
                            "url": "https://www.youtube.com/watch?v=OMJQPqG2Uas",
                            "title": "Keyword Research Tutorial: From Start to Finish",
                            "description": ""
                        }
                    ]
                },
                {
                    "type": "organic",
                    "items": [
                        {
                            "rank_type": 1,
                            "rank_serp": 8,
                            "page": 1,
                            "pixel": 1077,
                            "domain": "www.seoquantum.com",
                            "url": "https://www.seoquantum.com/en/blog/6-types-keywords-organic-seo",
                            "title": "The 6 Types of Keywords in Organic SEO",
                            "description": "2 mars 2024 — I will introduce you to 6 types of keywords that you absolutely need to know. We will start with the most common ones such as long-tail keywords and then move ...",
                            "rating": null,
                            "reviews": null
                        },
                        {
                            "rank_type": 2,
                            "rank_serp": 9,
                            "page": 1,
                            "pixel": 1223,
                            "domain": "storychief.io",
                            "url": "https://storychief.io/blog/seo-keyword-research-examples",
                            "title": "10 Clever SEO Keyword Research Examples",
                            "description": "Let's say you run a food blog. Some potential SEO keywords could be: quick weeknight dinners easy dinner recipes 30 minute meals one pot dinners",
                            "rating": null,
                            "reviews": null
                        },
                        {
                            "rank_type": 3,
                            "rank_serp": 10,
                            "page": 1,
                            "pixel": 1369,
                            "domain": "www.indeed.com",
                            "url": "https://www.indeed.com/career-advice/career-development/types-of-keywords",
                            "title": "19 Types of Keywords",
                            "description": "6 juin 2025 — 19 types of keywords and how to use them for marketing · 1. Market segment keywords · 2. Customer-defining keywords · 3. Product-defining ...",
                            "rating": null,
                            "reviews": null
                        },
                        {
                            "rank_type": 4,
                            "rank_serp": 11,
                            "page": 1,
                            "pixel": 1515,
                            "domain": "www.usg.edu",
                            "url": "https://www.usg.edu/galileo/skills/unit04/primer04_07.phtml",
                            "title": "Keyword Search",
                            "description": "In this case, the phrase alternative fuels and automobiles are the significant keywords.",
                            "rating": null,
                            "reviews": null
                        },
                        {
                            "rank_type": 5,
                            "rank_serp": 12,
                            "page": 1,
                            "pixel": 1639,
                            "domain": "guides.lib.uh.edu",
                            "url": "https://guides.lib.uh.edu/c.php?g=1249281",
                            "title": "What are keywords and why are they important? - Guides",
                            "description": "You probably used the title of the film and the word “showtimes” as your keywords to bring up the results you needed. Keywords in academic research are similar.",
                            "rating": null,
                            "reviews": null
                        },
                        {
                            "rank_type": 6,
                            "rank_serp": 13,
                            "page": 1,
                            "pixel": 1785,
                            "domain": "www.tactee.fr",
                            "url": "https://www.tactee.fr/seo/strategie-seo/keyword-seo/",
                            "title": "Qu'est ce qu'un keyword SEO ? [Définition & conseil]",
                            "description": "13 juil. 2024 — Commerciale : l'utilisateur compare des produits ou des services, par exemple « meilleur smartphone 2024 ». Identifier l'intention de recherche ...",
                            "rating": null,
                            "reviews": null
                        },
                        {
                            "rank_type": 7,
                            "rank_serp": 14,
                            "page": 1,
                            "pixel": 1931,
                            "domain": "backlinko.com",
                            "url": "https://backlinko.com/types-of-keywords",
                            "title": "10 Types of Keywords with Examples (+ How to Find Them)",
                            "description": "15 mai 2025 — 10 Types of Keywords with Examples (+ How to Find Them) · 1. Seed Keywords · 2. Informational Keywords · 3. Commercial Keywords · 4.",
                            "rating": null,
                            "reviews": null
                        },
                        {
                            "rank_type": 8,
                            "rank_serp": 15,
                            "page": 1,
                            "pixel": 2077,
                            "domain": "learn.microsoft.com",
                            "url": "https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/",
                            "title": "C# Keywords and contextual keywords - C# reference",
                            "description": "17 avr. 2025 — For example, @if is a valid identifier, but if isn't because if is a keyword. The first table in this article lists keywords that are ...",
                            "rating": null,
                            "reviews": null
                        }
                    ]
                },
                {
                    "type": "local_pack",
                    "items": [
                        {
                            "rank_type": 1,
                            "rank_serp": 19,
                            "page": 1,
                            "pixel": 2520,
                            "domain": "lebistrotm.fr",
                            "url": "https://lebistrotm.fr/",
                            "title": "Le Bistrot M",
                            "description": "",
                            "rating": 4.6,
                            "reviews": 220,
                            "price_range": "20–30 €",
                            "details": [
                                "20–30 €",
                                "Restaurant",
                                "1 Pl. Xavier Taillade",
                                "Fermé",
                                "Ouvre à 18:30",
                                "Repas sur place",
                                "Aucun plat à emporter",
                                "Pas de livraison"
                            ]
                        },
                        {
                            "rank_type": 2,
                            "rank_serp": 20,
                            "page": 1,
                            "pixel": 2661,
                            "domain": "www.domainedesoliviers.fr",
                            "url": "http://www.domainedesoliviers.fr/",
                            "title": "Domaine des Oliviers",
                            "description": "",
                            "rating": 4.5,
                            "reviews": 1600,
                            "price_range": null,
                            "details": [
                                "Française",
                                "4 All. Paul Emile d'Allard",
                                "Fermé",
                                "Ouvre à 19:00",
                                "Hôtel discret avec piscine et restaurant"
                            ]
                        }
                    ]
                },
                {
                    "type": "images",
                    "items": [
                        {
                            "rank_type": 1,
                            "rank_serp": 16,
                            "page": 1,
                            "pixel": 2311,
                            "domain": "searchfacts.com",
                            "url": "https://searchfacts.com/what-are-keywords-in-seo/",
                            "title": "",
                            "description": ""
                        },
                        {
                            "rank_type": 2,
                            "rank_serp": 17,
                            "page": 1,
                            "pixel": 2311,
                            "domain": "backlinko.com",
                            "url": "https://backlinko.com/hub/seo/seo-keywords",
                            "title": "",
                            "description": ""
                        },
                        {
                            "rank_type": 3,
                            "rank_serp": 18,
                            "page": 1,
                            "pixel": 2311,
                            "domain": "ahrefs.com",
                            "url": "https://ahrefs.com/blog/what-are-keywords/",
                            "title": "",
                            "description": ""
                        }
                    ]
                }
            ]
        }
    ]
}
Status: 400 Bad Request
{
    "error": "InvalidParameter",
    "message": "DESCRIPTION_OF_ERROR",
    "code": 400
}

URL de callback

Recuperação de SERPs por URL de callback
Você pode receber o resultado de uma SERP diretamente em uma URL informada ao criar a requisição; basta recuperar a chave HMAC associada à chave de API utilizada.
  • Código
  • PHP
  • Python
  • Javascript
  • Ruby
  • Java
  • C#
  • GO
// 1) Read the raw body (JSON)
$raw = file_get_contents('php://input');

// 2) Retrieve the headers
$headers = function_exists('getallheaders') ? getallheaders() : [];
$signature = $headers['X-Signature'] ?? '';

// 3) (Optional) Verify the HMAC signature
$sharedSecret = 'HMAC_KEY';
$expected = hash_hmac('sha256', $raw, $sharedSecret);
if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    header('Content-Type: text/plain; charset=utf-8');
    echo 'Invalid signature';
    exit;
}

// 4) Decode the JSON
$data = json_decode($raw, true);

if (json_last_error() !== JSON_ERROR_NONE) {
    http_response_code(400);
    header('Content-Type: text/plain; charset=utf-8');
    echo 'Invalid JSON';
    exit;
}

// 5) Process the data: a list holding the finished SERP
foreach ($data as $serp) {
    // $serp['id'], $serp['keyword'], $serp['results']...
}

// 6) Respond in JSON (optional, we log these responses for tracking purposes)
http_response_code(200);
header('Content-Type: application/json; charset=utf-8');
echo json_encode([
    'status' => 'ok',
    'received_at' => gmdate('c'),
    'echo' => array_column($data, 'id')
]);

Status de processamento das SERPs

Status atual do processamento das SERPs
Mostra o número de SERPs de acordo com o status:
Concluídas e resultados recuperados pelo usuário (status=done, fetched=true)
Concluídas e resultados não recuperados pelo usuário (status=done, fetched=false)
Em processamento (status=processing)
Pendentes (status=pending)
get
https://api.semscraper.com/v1/serp/status
Autorizações : Bearer {api_key}
  • Requisição
  • Resposta bem-sucedida
Status: 200 OK
{
    "status": "success",
    "request_ms": 54,
    "count": 4,
    "data": [
        {
            "status": "done",
            "fetched": true,
            "count": 5
        },
        {
            "status": "done",
            "fetched": false,
            "count": 1000
        },
        {
            "status": "processing",
            "count": 0
        },
        {
            "status": "pending",
            "count": 0
        }
    ]
}

Histórico de requisições

Lista suas requisições, da mais recente para a mais antiga, com a configuração de cada uma (palavra-chave, mecanismo de busca, dispositivo, localização, idioma, profundidade…) e o status, sem o resultado da SERP.
Todas as requisições da conta são retornadas, qualquer que seja o status e tenham elas já sido recuperadas ou não. Esta chamada não as marca como recuperadas.

Para paginar, chame o endpoint novamente com o parâmetro cursor igual ao next_cursor da resposta anterior, enquanto has_more for true. O link _links.next contém a URL pronta para uso. Para obter o resultado de uma requisição, use o link _links.json ou _links.html dela.
Limite
10.000 requisições por chamada
get
https://api.semscraper.com/v1/serp/list?date=2026-10-10&limit=1000
Autorizações : Bearer {api_key}
Parâmetros
date
string
Dia de criação das requisições, no formato YYYY-MM-DD (por exemplo, 2026-10-04). Sem este parâmetro, todas as datas são retornadas.
status
string
Filtro por status: pending, processing ou done. Sem este parâmetro, todos os status são retornados.
limit
integer
Número de requisições por página, de 1 a 10.000. O padrão é 1.000.
cursor
string
Cursor de paginação: o valor next_cursor da resposta anterior. Omita-o na primeira página.
  • Requisição
  • Resposta bem-sucedida
  • Resposta de erro
Status: 200 OK
{
    "status": "success",
    "request_ms": 38,
    "count": 2,
    "has_more": true,
    "next_cursor": "MTI4NDU2Nzg5",
    "data": [
        {
            "id": "SERP_ID",
            "search_engine": "google_search",
            "keyword": "example keyword",
            "device": "desktop",
            "location": "fr",
            "language": "fr",
            "depth": 1,
            "geolocation": null,
            "priority": 1,
            "callback_url": null,
            "status": "done",
            "fetched": false,
            "cost": 0.0003,
            "created_at": "2026-10-04 09:12:45",
            "updated_at": "2026-10-04 09:12:58",
            "_links": {
                "json": {
                    "href": "/v1/serp?ids=SERP_ID&output=json",
                    "method": "GET",
                    "type": "application/json"
                },
                "html": {
                    "href": "/v1/serp?ids=SERP_ID&output=html",
                    "method": "GET",
                    "type": "application/json"
                }
            }
        },
        {
            "id": "SERP_ID",
            "search_engine": "google_maps",
            "keyword": "example keyword",
            "device": null,
            "location": "fr",
            "language": "fr",
            "depth": 1,
            "geolocation": "Nice, Alpes-Maritimes, France",
            "priority": 1,
            "callback_url": "https://example.com/callback",
            "status": "pending",
            "fetched": false,
            "cost": 0.0003,
            "created_at": "2026-10-04 09:12:44",
            "updated_at": null,
            "_links": {
                "json": {
                    "href": "/v1/serp?ids=SERP_ID&output=json",
                    "method": "GET",
                    "type": "application/json"
                },
                "html": {
                    "href": "/v1/serp?ids=SERP_ID&output=html",
                    "method": "GET",
                    "type": "application/json"
                }
            }
        }
    ],
    "_links": {
        "next": {
            "href": "/v1/serp/list?date=2026-10-04&limit=1000&cursor=MTI4NDU2Nzg5",
            "method": "GET",
            "type": "application/json"
        }
    }
}
Status: 400 Bad Request
{
    "error": "InvalidParameter",
    "message": "Invalid format for parameter: date",
    "code": 400
}

Faturamento

Saldo restante

Recupera o saldo restante
get
https://api.semscraper.com/v1/billing/credit
Autorizações : Bearer {api_key}
  • Requisição
  • Resposta bem-sucedida
Status: 200 OK
{
    "status": "success",
    "request_ms": 21,
    "count": 1,
    "data": [
        {
            "balance": 100.50
        }
    ]
}

Formas de pagamento

Formas de pagamento disponíveis
get
https://api.semscraper.com/v1/billing/payment_methods
Autorizações : Bearer {api_key}
  • Requisição
  • Resposta bem-sucedida
Status: 200 OK
{
    "status": "success",
    "request_ms": 43,
    "count": 3,
    "data": [
        {
            "id": 1,
            "name": "Perso",
            "num": "-4242",
            "expiration": "1226",
            "type": "Visa",
            "master": false
        },
        {
            "id": 30,
            "name": "Pro",
            "num": "-4444",
            "expiration": "1227",
            "type": "Mastercard",
            "master": true
        }
    ]
}