# Referencia del API SERP: GET /search y GET /credits

> Referencia del API SERP de SerpCrypto: parámetros de GET /search, motores, valores por defecto y códigos de error, con curl, Python y Node.js.

- URL: https://serpcrypto.com/es/docs/search/
- Última actualización: 2026-10-22
- Editor: SerpCrypto (https://serpcrypto.com)

Todos los parámetros, valores por defecto y códigos de error del API SerpCrypto, versión 1. URL base: `https://serpcrypto.com/api/v1`. Todas las peticiones usan HTTPS; todas las respuestas son JSON en UTF-8.

**Respuesta rápida — ¿Qué parámetros acepta el endpoint de búsqueda de SerpCrypto?**

`GET https://serpcrypto.com/api/v1/search` acepta un parámetro obligatorio, `q`, y nueve opcionales: `engine`, `gl`, `hl`, `location`, `google_domain`, `device`, `page`, `safe` y `period`. **SerpCrypto** devuelve JSON y cobra 1 crédito por búsqueda exitosa en los 6 motores; los errores son gratis. Los packs empiezan en 7,50 US$ por 10.000 búsquedas, pagando con criptomonedas y sin KYC.

## ¿Cómo me autentico?

Envía tu clave de una de estas dos formas. La recomendada es el header `Authorization: Bearer YOUR_KEY`. La otra es el parámetro de consulta `api_key=YOUR_KEY`, práctico para una prueba rápida en una pestaña del navegador.

Una clave ausente, incorrecta o revocada devuelve `401 invalid_api_key` y no cuesta nada. Claves API que puedes crear y revocar en cualquier momento desde tu dashboard, así puedes dar su propia clave a cada script o servidor y revocar una sin tocar las demás.

## Ejecutar una búsqueda

`GET /api/v1/search`

Ejecuta una búsqueda en el motor elegido y devuelve la página de resultados en JSON. Una búsqueda exitosa usa 1 crédito, sea cual sea el motor; un error no usa ninguno. Los parámetros van en el query string, codificados en URL. El ejemplo pide a Google tostadores de café en Austin, Texas; los IDs, recuentos y resultados son ilustrativos.

Autenticación: clave API en el header `Authorization: Bearer API_KEY`.

**Parámetros**

| Nombre | En | Tipo | Obligatorio | Descripción |
| --- | --- | --- | --- | --- |
| `q` | query | string | Sí | La consulta de búsqueda, tal como la escribiría una persona. Los operadores de búsqueda como las comillas o `site:` forman parte de la consulta. |
| `engine` | query | string | No | `google` (por defecto), `google_news`, `google_images`, `google_maps`, `google_shopping` o `bing`. |
| `gl` | query | string | No | País de los resultados: código ISO 3166-1 alpha-2 en minúsculas, como `us`, `de` o `br`. Por defecto, `us`. |
| `hl` | query | string | No | Idioma de la interfaz, como `en`, `de` o `pt-BR`. Por defecto, `en`. |
| `location` | query | string | No | Lugar a nivel de ciudad, escrito `City, Region, Country`, como `Austin, Texas, United States`. Consulta [ubicaciones](https://serpcrypto.com/es/docs/locations/). |
| `google_domain` | query | string | No | Dominio de Google en el que buscar, como `google.de`. Por defecto: el dominio del país de `gl`. Se ignora cuando `engine=bing`. |
| `device` | query | string | No | `desktop` (por defecto) o `mobile`. |
| `page` | query | integer | No | Página de resultados desde 1 (por defecto) hasta 10. Cada página es una búsqueda independiente y consume 1 crédito. |
| `safe` | query | string | No | `active` filtra los resultados explícitos; `off` (por defecto) no. |
| `period` | query | string | No | Solo resultados de la última hora (`h`), día (`d`), semana (`w`), mes (`m`) o año (`y`). |
| `api_key` | query | string | No | Tu clave, si no envías el header `Authorization`. |

**Respuesta** `200`

```json
{
  "search_metadata": {
    "id": "srch_7f3a9c2e41b8",
    "status": "success",
    "engine": "google",
    "created_at": "2026-10-22T09:14:05Z",
    "credits_used": 1
  },
  "search_parameters": {
    "engine": "google",
    "q": "coffee roasters",
    "gl": "us",
    "hl": "en",
    "location": "Austin, Texas, United States",
    "google_domain": "google.com",
    "device": "desktop",
    "page": 1
  },
  "search_information": {
    "total_results": 18600000,
    "query_displayed": "coffee roasters"
  },
  "local_results": [
    {
      "position": 1,
      "title": "Example Coffee Roasters",
      "address": "123 Example St, Austin, TX",
      "rating": 4.7,
      "reviews": 312,
      "type": "Coffee roasters"
    }
  ],
  "organic_results": [
    {
      "position": 1,
      "title": "The 12 best coffee roasters in Austin",
      "link": "https://www.example.com/austin/coffee-roasters",
      "displayed_link": "www.example.com › austin › coffee",
      "snippet": "From light Nordic roasts to dark espresso blends, these local roasters…",
      "date": "Sep 30, 2026"
    },
    {
      "position": 2,
      "title": "Example Roasting Co. | Fresh beans, roasted in Austin",
      "link": "https://www.example.org/",
      "displayed_link": "www.example.org",
      "snippet": "Small-batch coffee roasted every weekday and shipped the same day…"
    }
  ],
  "people_also_ask": [
    {
      "question": "What is the oldest coffee roaster in Austin?",
      "snippet": "…",
      "title": "Austin coffee history",
      "link": "https://www.example.net/austin-coffee-history"
    }
  ],
  "related_searches": [
    {
      "query": "coffee roasters near me"
    },
    {
      "query": "coffee roasters austin wholesale"
    }
  ],
  "pagination": {
    "current": 1,
    "next_page": 2
  }
}
```

*curl*

```bash
curl -sG "https://serpcrypto.com/api/v1/search" \
  -H "Authorization: Bearer $SERPCRYPTO_API_KEY" \
  --data-urlencode "q=coffee roasters" \
  --data-urlencode "location=Austin, Texas, United States" \
  -d gl=us -d hl=en -d device=desktop
```

*Python*

```python
import os

import requests

r = requests.get(
    "https://serpcrypto.com/api/v1/search",
    params={
        "q": "coffee roasters",
        "location": "Austin, Texas, United States",
        "gl": "us",
        "hl": "en",
    },
    headers={"Authorization": "Bearer " + os.environ["SERPCRYPTO_API_KEY"]},
    timeout=60,
)
r.raise_for_status()
print(r.json()["organic_results"][0]["link"])
```

*Node.js*

```javascript
const params = new URLSearchParams({
  q: "coffee roasters",
  location: "Austin, Texas, United States",
  gl: "us",
  hl: "en",
});
const res = await fetch("https://serpcrypto.com/api/v1/search?" + params, {
  headers: { Authorization: "Bearer " + process.env.SERPCRYPTO_API_KEY },
});
const data = await res.json();
console.log(data.organic_results?.[0]?.link);
```

## ¿Qué valores de engine existen y qué devuelve cada uno?

El frame (`search_metadata`, `search_parameters`, `search_information`) es el mismo en todos los engines. Un bloque aparece solo cuando la página lo muestra.

| `engine` | Fuente | Bloques principales de la respuesta |
| --- | --- | --- |
| `google` | Google Search | `ai_overview`, `organic_results`, `ads`, `people_also_ask`, `local_results`, `knowledge_graph`, `top_stories`, `inline_videos`, `shopping_results`, `related_searches`, `pagination` |
| `google_news` | Google News | `news_results`: title, link, source, date, snippet, thumbnail |
| `google_images` | Google Images | `images_results`: URL y tamaño originales, thumbnail, página de origen |
| `google_maps` | Google Maps | `local_results`: name, address, phone, website, rating, reviews, category, hours, coordinates |
| `google_shopping` | Google Shopping | `shopping_results`: title, price, extracted price, currency, merchant, delivery, rating |
| `bing` | Bing | `organic_results`, `related_searches` |

## Consultar tus créditos

`GET /api/v1/credits`

Devuelve los créditos que quedan en tu cuenta, los créditos usados desde medianoche UTC y el número de búsquedas que tu cuenta puede ejecutar al mismo tiempo. Esta llamada es gratis. Los valores siguientes son ejemplos.

Autenticación: clave API en el header `Authorization: Bearer API_KEY`.

**Respuesta** `200`

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

*curl*

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

*Python*

```python
import os

import requests

r = requests.get(
    "https://serpcrypto.com/api/v1/credits",
    headers={"Authorization": "Bearer " + os.environ["SERPCRYPTO_API_KEY"]},
    timeout=30,
)
r.raise_for_status()
print(r.json()["credits_remaining"])
```

*Node.js*

```javascript
const res = await fetch("https://serpcrypto.com/api/v1/credits", {
  headers: { Authorization: "Bearer " + process.env.SERPCRYPTO_API_KEY },
});
const { credits_remaining } = await res.json();
console.log(credits_remaining);
```

## ¿Qué errores puede devolver la API?

Todos los errores tienen el body `{"error": {"code": "…", "message": "…"}}`. La [página de errores](https://serpcrypto.com/es/docs/errors/) explica cada uno y muestra el código de reintento.

| HTTP | `code` | Cuándo ocurre | Se cobra |
| --- | --- | --- | --- |
| 400 | `invalid_parameter` | Falta un parámetro obligatorio o un valor está fuera de la lista permitida | No |
| 401 | `invalid_api_key` | La clave falta, es incorrecta o fue revocada | No |
| 402 | `insufficient_credits` | Tu cuenta no tiene créditos disponibles | No |
| 429 | `concurrency_limit` | Hay demasiadas búsquedas en ejecución al mismo tiempo en tu cuenta | No |
| 502 | `search_failed` | El engine o la recopilación falló en esta solicitud; reinténtala | No |
| 504 | `search_timeout` | No hay respuesta a tiempo; reinténtala | No |

## ¿Qué se cobra, exactamente?

- **Una búsqueda exitosa = un crédito**, en todos los engines, incluidos Google Maps y Google Shopping.
- **Cada página de resultados es una búsqueda.** 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.
- **Los errores son gratis:** toda respuesta con un estado HTTP distinto de 200 no consume créditos.
- **Consultar tus créditos es gratis.**

Los créditos de búsqueda prepagados no caducan nunca: las consultas sin usar se quedan en tu cuenta hasta que las uses. Los packs van desde 7,50 US$ por 10.000 búsquedas hasta 0,30 US$/1K búsquedas en el más grande; consulta [precios](https://serpcrypto.com/es/pricing/).

## ¿Cómo debo codificar la consulta?

Envía `q` codificado como URL, igual que cualquier valor de query string: un espacio se convierte en `%20` o `+`, y las letras acentuadas se codifican como UTF-8. curl lo hace con `--data-urlencode`, Python `requests` y `httpx` lo hacen con `params=`, y Node.js lo hace con `URLSearchParams`.

Escribe la consulta exactamente como la escribiría una persona en el cuadro de búsqueda. Las comillas, el signo menos o `site:` permanecen dentro de `q`; el engine decide cómo aplicarlos, igual que lo haría para un visitante.

## ¿La API tiene versionado?

Sí. La versión forma parte del path: `/api/v1/`. En las respuestas de la versión 1 pueden aparecer campos o bloques nuevos, así que tu código debería ignorar las claves que no conozca. Eliminar o renombrar un campo llegaría con una nueva versión en el path, no como un cambio en `v1`.

## Preguntas sobre la referencia de la API

### ¿Puedo enviar una solicitud POST con un cuerpo JSON?

No en la versión 1: ambos endpoints aceptan solicitudes GET con los parámetros en la cadena de consulta. Así toda llamada es fácil de reproducir con curl o un navegador, y fácil de registrar sin el cuerpo.

### ¿Cuántos resultados devuelve una búsqueda?

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. Para reunir 30 resultados, solicita `page=1`, `page=2` y `page=3`: tres búsquedas, tres créditos.

### ¿Qué pasa cuando se me acaban los créditos?

La siguiente búsqueda devuelve `402 insufficient_credits` y no consume nada. Compra otro pack con tu saldo en la [página de precios](https://serpcrypto.com/es/pricing/); tu clave sigue funcionando y las búsquedas se reanudan al instante.

### ¿Puedo usar la misma clave desde varios servidores?

Sí. Una clave no está ligada a una dirección IP. Lo que está limitado es el número de búsquedas que se ejecutan a la vez en la cuenta: `concurrency_limit` en `GET /credits` da la cifra.

---

SerpCrypto: SerpCrypto es una API SERP para desarrolladores y agentes de IA que devuelve resultados de Google y Bing como JSON, pagada con criptomonedas sin subir ningún documento de identidad. Los créditos de búsqueda prepagados desde 0,30 US$/1K búsquedas nunca caducan. Sin KYC: ni identificación, ni selfie, ni documentos. Paga con criptomonedas.