Inicio rápido de la API SERP: tu primera búsqueda en curl, Python y Node.js

¿Cómo ejecuto mi primera búsqueda con curl?

Exporta la clave una vez y luego envía una solicitud GET. La opción -G con --data-urlencode arma la cadena de consulta y codifica los espacios y acentos por ti. La respuesta es un único documento JSON, y jq lo mantiene legible en una terminal.

El ejemplo consulta Google, el motor predeterminado, con resultados de EE. UU. en inglés. Cambia q, gl o hl y vuelve a ejecutarlo: cada ejecución exitosa usa un crédito.

export SERPCRYPTO_API_KEY="paste-your-key-here"

curl -sG "https://serpcrypto.com/api/v1/search" \
  -H "Authorization: Bearer $SERPCRYPTO_API_KEY" \
  --data-urlencode "q=best espresso grinder" \
  -d gl=us -d hl=en | jq '.organic_results[:3]'

¿Cómo ejecuto la misma búsqueda en Python?

Usa cualquier cliente HTTP. Con requests, pasa los parámetros como un diccionario y la clave en el header. raise_for_status() convierte una respuesta de error, como 401 por una clave incorrecta, en una excepción que puedes capturar.

import os

import requests

API_URL = "https://serpcrypto.com/api/v1/search"
API_KEY = os.environ["SERPCRYPTO_API_KEY"]

response = requests.get(
    API_URL,
    params={"q": "best espresso grinder", "gl": "us", "hl": "en"},
    headers={"Authorization": f"Bearer {API_KEY}"},
    timeout=60,
)
response.raise_for_status()
data = response.json()

print("credits used:", data["search_metadata"]["credits_used"])
for result in data.get("organic_results", [])[:3]:
    print(result["position"], result["title"], result["link"])

¿Y en Node.js?

Node.js 18 y posteriores incluyen fetch, así que no hace falta ningún paquete. Guarda el archivo con la extensión .mjs para usar await en el nivel superior y luego ejecuta node first-search.mjs.

// first-search.mjs (Node.js 18 or later: fetch and top-level await are built in)
const API_URL = "https://serpcrypto.com/api/v1/search";
const params = new URLSearchParams({ q: "best espresso grinder", gl: "us", hl: "en" });

const response = await fetch(`${API_URL}?${params}`, {
  headers: { Authorization: `Bearer ${process.env.SERPCRYPTO_API_KEY}` },
});
if (!response.ok) {
  throw new Error(`HTTP ${response.status}: ${await response.text()}`);
}
const data = await response.json();

console.log("credits used:", data.search_metadata.credits_used);
for (const result of (data.organic_results ?? []).slice(0, 3)) {
  console.log(result.position, result.title, result.link);
}

¿Cómo compruebo cuántos créditos me quedan?

Llama a GET https://serpcrypto.com/api/v1/credits con la misma clave. Es gratis y devuelve tres números: créditos restantes, créditos usados hoy y cuántas búsquedas puede ejecutar tu cuenta al mismo tiempo. Cada cuenta puede ejecutar un número determinado de consultas al mismo tiempo; el límite se muestra en tu dashboard y se amplía a petición.

curl -s "https://serpcrypto.com/api/v1/credits" -H "Authorization: Bearer $SERPCRYPTO_API_KEY"

{
  "credits_remaining": 84210,
  "credits_used_today": 1290,
  "concurrency_limit": 10
}

¿Qué devuelve una búsqueda?

Todas las respuestas tienen la misma estructura en todos los motores. search_metadata indica si la búsqueda se realizó correctamente y cuántos créditos consumió. search_parameters repite los ajustes aplicados, incluidos los valores predeterminados. Después viene un array u objeto por cada bloque de la página de resultados, como organic_results o people_also_ask.

Un bloque solo aparece cuando la página lo muestra, así que léelo con un valor predeterminado. La página del formato de respuesta describe cada bloque y campo.

{
  "search_metadata": { "id": "srch_7f3a9c2e41b8", "status": "success", "engine": "google", "credits_used": 1 },
  "search_parameters": { "engine": "google", "q": "best espresso grinder", "gl": "us", "hl": "en", "page": 1 },
  "search_information": { "total_results": 18600000, "query_displayed": "best espresso grinder" },
  "organic_results": [ { "position": 1, "title": "…", "link": "https://www.example.com/…", "snippet": "…" } ],
  "people_also_ask": [ { "question": "…", "snippet": "…", "link": "https://www.example.org/…" } ],
  "related_searches": [ { "query": "best espresso grinder under 300" } ],
  "pagination": { "current": 1, "next_page": 2 }
}

¿Cuánto cuesta una búsqueda y cuándo es gratis?

1 crédito = 1 consulta correcta, que devuelve una página de resultados en cualquier motor compatible. Una consulta fallida no se cobra. Unos 10 resultados orgánicos por página, tal como Google los sirve desde que dejó de respetar num=100 en septiembre de 2025; cada página adicional es un crédito más. Una solicitud rechazada por un parámetro incorrecto, una clave equivocada, un saldo vacío o una cuenta ocupada también es gratis, y también lo es cada llamada al endpoint de créditos.

Los precios van desde 7,50 US$ por 10.000 búsquedas hasta 0,30 US$/1K búsquedas en el pack más grande, a fecha de octubre de 2026. Los créditos de búsqueda prepagados no caducan nunca: las consultas sin usar se quedan en tu cuenta hasta que las uses. La página de errores enumera cada código de error y la forma correcta de reintentar.