• Informações
  • Limites de chamadas
  • Versões Google
  • Lista de versões
  • SERPs do Google
  • Criar consultas
  • IDs de consulta
  • Recuperar SERPs
  • URL de chamada de retorno
  • Estado de processamento dos SERPs
  • Faturação
  • Crédito remanescente
  • Métodos de pagamento

Informações

Limite do número de chamadas à API
GET : 100 appels par minute
POST : 100 appels par minute

Versões Google

Obter os parâmetros localização e idioma necessários para obter os SERPs do Google.
get
https://api.semscraper.com/v1/serp/google/location
Autorizações : Bearer {api_key}
  • Pedido
  • 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 do Google

Criar consultas SERPs do Google
Os dados devem ser enviados numa matriz JSON. Cada elemento deve conter os seguintes campos.
Limite
A matriz JSON pode conter 100 elementos, pelo que pode criar 100 SERPs scrapes numa única chamada.
post
https://api.semscraper.com/v1/serp/google
Autorizações : Bearer {api_key}
Parâmetros
search_engine
Necessário
string
Escolha do motor de busca :
Pesquisa Google (valor: google_search)
keyword
Necessário
string
Palavras-chave a pesquisar no motor de busca
device
Necessário
string
Escolha do substrato :
Computador (valor: desktop)
Móvel (valor: móvel)
depth
Necessário
integer
Profundidade da página, recuperamos os SERPs do Google com paginação. Este parâmetro deve estar entre 1 (aproximadamente 10 resultados) e 10 (aproximadamente 100 resultados).
location
Necessário
string
Código de localização do motor de busca
language
Necessário
string
Língua do motor de busca
geolocation
string
Permite-lhe geolocalizar um SERP do Google. Por exemplo, pode indicar a cidade, o departamento ou o país, separados por uma vírgula.
priority
integer
Utilizado para dar prioridade aos seus pedidos, que são processados por ordem decrescente de prioridade. Valor entre 1 e 10.
callback_url
string
Permite-lhe especificar um URL para o qual lhe enviaremos os resultados da palavra-chave depois de esta ter sido processada.
  • Pedido
  • Resposta bem sucedida
  • Resposta ao erro
Status: 200 OK
{
    "status": "success",
    "request_ms": 40,
    "count": 1,
    "currency": "EUR",
    "total_cost": 2.0e-5,
    "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": 2.0e-51,
            "_links": {
                "json": {
                    "href": "/serp/google?ids=SERP_ID&output=json",
                    "method": "GET",
                    "type": "application/json"
                },
                "html": {
                    "href": "/serp/google?ids=SERP_ID&output=html",
                    "method": "GET",
                    "type": "application/json"
                }
            }
        }
    

}
Status: 400 Bad Request
{
    "error": "Bad Request",
    "message": "DESCRIPTION_OF_ERROR",
    "code": 400
}
Lista de identificadores (IDs) para SERPs concluídos que ainda não foram recuperados.
Este método permite-lhe obter os IDs de todos os SERPs que já foram processados mas ainda não recuperados. Pode então chamar o método de recuperação de SERPs do Google utilizando estes IDs.
get
https://api.semscraper.com/v1/serp/google
Autorizações : Bearer {api_key}
  • Pedido
  • 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.00010",
            "_links": {
                "json": {
                    "href": "/serp/google?ids=SERP_ID&output=json",
                    "method": "GET",
                    "type": "application/json"
                },
                "html": {
                    "href": "/serp/google?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.00010",
            "_links": {
                "json": {
                    "href": "/serp/google?ids=SERP_ID&output=json",
                    "method": "GET",
                    "type": "application/json"
                },
                "html": {
                    "href": "/serp/google?ids=SERP_ID&output=html",
                    "method": "GET",
                    "type": "application/json"
                }
            }
        }
    

}
Recuperar Google SERPs através dos seus IDs
Recupere vários SERPs numa única chamada (em formato JSON ou HTML) fornecendo vários IDs separados por uma vírgula.
Limite
Pode especificar um máximo de 100 IDs, o que lhe permite obter 100 SERPs numa única chamada.
get
https://api.semscraper.com/v1/serp/google?ids=id1,id2&output=json
Autorizações : Bearer {api_key}
Parâmetros
ids
Necessário
string
Lista de IDs separada por vírgulas.
output
Necessário
string
Escolha do formato de saída :
JSON (valor: json)
HTML (valor: html)
  • Pedido
  • Resposta bem sucedida
  • Resposta ao 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.00002",
            "created_at": "2025-09-10T12:32:56Z",
            "scraped_at": "2025-09-10T12:33:02Z",
            "duration_ms": 5403,
            "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 ..."
                        },
                        {
                            "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"
                        },
                        {
                            "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 ..."
                        },
                        {
                            "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."
                        },
                        {
                            "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."
                        },
                        {
                            "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 ..."
                        },
                        {
                            "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."
                        },
                        {
                            "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 ..."
                        }
                    

                },
                {
                    "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
}
Recuperação de SERPs através de um URL de retorno de chamada
Pode receber o resultado de um SERP diretamente num URL que nos fornece quando cria uma consulta, bastando para isso recuperar a chave HMAC associada à chave 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
/
$data contains what you sent in the $payload from the client side.
For example : $data'id', $data'results', etc.
/

// 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' => $data'id' ?? null
);
Estado atual do processamento das SERPs
Ver o número de SERPs de acordo com o seu estado:
Concluído e resultados recuperados pelo utilizador (status=done, fetched=true)
Concluído e resultados não recuperados pelo utilizador (status=done, fetched=false)
Em processamento (status=processamento)
Em espera (estado=pendente)
get
https://api.semscraper.com/v1/serp/google/status
Autorizações : Bearer {api_key}
  • Pedido
  • 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
        }
    

}

Faturação

Recupera o crédito remanescente
get
https://api.semscraper.com/v1/billing/credit
Autorizações : Bearer {api_key}
  • Pedido
  • Resposta bem sucedida
Status: 200 OK
{
    "status": "success",
    "request_ms": 21,
    "count": 1,
    "data":
        {
            "balance": 100.50
        }
    

}
Métodos de pagamento disponíveis
get
https://api.semscraper.com/v1/billing/payment_methods
Autorizações : Bearer {api_key}
  • Pedido
  • 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
        }
    

}