API Reference

The Dataswap API

One REST API for structured, AI-ready web intelligence — SERP, keywords, competitive intelligence, backlinks, on-page, business and marketplace data. JSON in, clean JSON out. Every data endpoint reserves and commits credits atomically, and reports your balance in response headers.

Production readyReal-time datahttps://api.dataswap.io

install · node

npm install dataswap

# or, without waiting for the npm release:
npm install https://dataswap.io/sdk/dataswap-latest.tgz

install · python

pip install dataswap

# or, without waiting for the PyPI release:
pip install https://dataswap.io/sdk/dataswap-python-latest.tar.gz

Both official clients handle the 202 handoff, idempotent retries and typed errors for you. The Python one has no dependencies.

Open the API reference Download OpenAPI 3.1 specalso at GET /v1/openapi.yaml

Overview

The Dataswap API is organised into service groups, each backed by a resilient data pipeline and normalised into a stable, documented JSON envelope. All data endpoints are POST requests that accept a JSON body and return a 200 OK with the parsed result and billing metadata. Read the getting-started sections below once, then jump to the service you need.

· Predictable JSON envelopes with search_metadata on every response.
· Prepaid credits with reserve → commit accounting and header-level balance.
· Idempotency keys for safe retries on every billable call.
· Typed error bodies with a stable code and a request id.

Authentication

Authenticate every request with an API key. Send it as a bearer token in the Authorization header (the X-API-Key header is also accepted). Keys are prefixed by mode: sk_live_… for live keys and sk_test_… for test keys. Test keys exercise the full API surface without spending real credits. Create, list and revoke keys from your dashboard or via the Account & Platform endpoints. Keys carry scopes — read for data endpoints, admin for key management.

Authorization header

# Bearer token (recommended)
curl https://api.dataswap.io/v1/usage \
  -H "Authorization: Bearer sk_live_9f2c...4b1a"

# or the X-API-Key header
curl https://api.dataswap.io/v1/usage \
  -H "X-API-Key: sk_live_9f2c...4b1a"

Treat keys like passwords: never embed a live key in client-side code. A missing or invalid key returns 401 authentication_error; a valid key without the required scope returns 403 insufficient_scope.

Base URL

All endpoints live under a single host and the /v1 version prefix. The health probe at /health is the only route outside the prefix.

Base URL

https://api.dataswap.io/v1

Credits & pricing model

Dataswap is prepaid. Each billable call has a base credit cost, multiplied by a freshness factor and plus any enrichments:

cost model

cost = base_cost × freshness_multiplier + Σ enrichments

freshness:  cached ×0.5   fresh ×1 (default)   live ×1.5

Credits are handled with a reserve → commit flow: the cost is reserved before we call upstream and only committed once we have a result to hand back. If the upstream fetch fails, the reservation is refunded — you are never charged for a call we could not serve. A freshness: "cached" miss costs 0 credits and returns cache_miss.

Operation	Base credits
search / news	1
maps	2
business_info	2
keywords	3
amazon_products	3
domain_technologies	3
app_search	3
labs_ranked_keywords / labs_competitors	4
onpage_summary	4
backlinks_summary	5
content_search	5

Every billable response includes your balance in headers:

credit headers

X-Request-Id: req_01HZX8...        # unique id for this request (also in the body)
X-Credits-Used: 1                  # credits committed for this call
X-Credits-Remaining: 9841          # balance after this call

Running low returns 402 insufficient_credits with the amount needed and your balance. The live price book (credit cost per operation) is available at GET /v1/pricing.

Rate limits

Requests are rate limited per API key on a fixed one-minute window (anonymous requests are limited per IP, more tightly). Every response carries the current window state, and a 429 includes a Retry-After hint in seconds.

rate-limit headers

X-RateLimit-Limit: 120             # requests allowed in the window
X-RateLimit-Remaining: 118         # requests left in the current window
X-RateLimit-Reset: 1770000000      # unix time when the window resets
Retry-After: 42                    # (on 429 only) seconds to wait

Need higher limits? Contact us at support@dataswap.io.

Idempotency

Every billable call accepts an Idempotency-Key header. Retrying with the same key returns the original response — headers included — and is never charged twice. Reusing a key with a different request body is rejected, so a stale key can never replay the wrong query. A key whose original request is still in flight returns 409 idempotency_in_flight.

idempotent request

curl -X POST https://api.dataswap.io/v1/search \
  -H "Authorization: Bearer sk_live_9f2c...4b1a" \
  -H "Idempotency-Key: 6f9d2c1e-4b2a-4f8e-9c1d-1a2b3c4d5e6f" \
  -H "Content-Type: application/json" \
  -d '{ "q": "best running shoes" }'

# a replay echoes the original result:
# X-Idempotent-Replay: true

Long-running jobs

Some operations — Amazon data, reviews, business profiles, app data — take longer than it makes sense to hold an HTTP connection open for. If the result does not arrive within about 25 seconds, the API hands the work off instead of timing out: you get a 202 Accepted with a job_id, the work carries on server-side, and you poll GET /v1/jobs/:id until it is done.

The same endpoint can answer 200 or 202 depending on how long the upstream takes, so handle both. Do not resubmit the request on a 202 — the job is already running, and a second call is a second job.

202 handoff

{
  "job_id": "9f1c7e2a-4b1d-4a3e-8c55-2f6b0d9e1a34",
  "status": "processing",
  "request_id": "req_01HZX8...",
  "credits_reserved": 3,
  "poll_url": "/v1/jobs/9f1c7e2a-4b1d-4a3e-8c55-2f6b0d9e1a34"
}

poll until done

curl https://api.dataswap.io/v1/jobs/9f1c7e2a-4b1d-4a3e-8c55-2f6b0d9e1a34 \
  -H "Authorization: Bearer sk_live_9f2c...4b1a"

# {"job_id":"9f1c...","status":"processing","credits_used":null,"result":null}
# ... poll every 2-5s ...
# {"job_id":"9f1c...","status":"done","credits_used":3,"result":{ ... }}

What a 202 costs you

Nothing, until there is a result. The credits are reserved, not debited — which is why credits_used stays null while the job runs, and why a job that fails refunds the reservation in full. We never charge for a result we did not deliver.

Errors

Errors use conventional HTTP status codes and a single typed JSON envelope. The type groups the error, the code is a stable machine-readable string, and request_id matches the X-Request-Id header for support.

error envelope

{
  "error": {
    "code": "insufficient_credits",
    "message": "Insufficient credits: 5 needed, 2 available.",
    "type": "insufficient_credits",
    "request_id": "req_01HZX8..."
  }
}

HTTP	type	When
400	invalid_request	Malformed body, unknown field, or a validation failure.
401	authentication_error	Missing or invalid API key.
402	insufficient_credits	Not enough credits to serve the call.
403	forbidden	Valid key without the required scope.
404	not_found	Unknown route, or a cache miss on freshness="cached".
409	conflict	An idempotency key is still in flight.
429	rate_limited	Rate limit exceeded — see Retry-After.
502	upstream_error	The upstream data source failed (call is refunded).
500	internal_error	Unexpected server error.

Services

Sixteen service groups covering search, intelligence, links, on-page, business and marketplace data, plus the AI tools and catalog extraction.

SERP · Google Search

Full Google organic SERP as structured JSON — organic results, ads, PAA, knowledge graph and related searches.

POST/v1/search

Run a Google Search query and return a parsed SERP.

Scope: read
Cost: 1 credit (base) × freshness multiplier

Request body

Field	Type	Req.	Description
q	string	yes	Search query (1–400 chars).
gl	string	no	Two-letter country code (e.g. "us", "pt"). Default "us".
hl	string	no	UI language code (e.g. "en"). Default "en".
location	string	no	Full location name, e.g. "Lisbon,Portugal".
device	enum	no	"desktop" \| "mobile". Default "desktop".
num	integer	no	Results per page (1–100). Default 10.
page	integer	no	Page number (1–50). Default 1.
freshness	enum	no	"cached" (0.5×) \| "fresh" (1×) \| "live" (1.5×). Default "fresh".

Example request

cURL

curl -X POST https://api.dataswap.io/v1/search \
  -H "Authorization: Bearer sk_live_9f2c...4b1a" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "best running shoes",
    "gl": "us",
    "hl": "en",
    "num": 10,
    "freshness": "fresh"
  }'

Example response

200 OK

{
  "search_metadata": {
    "id": "req_01HZX8...",
    "status": "success",
    "created_at": "2026-07-20T10:14:03Z",
    "engine": "google_search",
    "credits_used": 1,
    "cached": false,
    "latency_ms": 842
  },
  "search_parameters": {
    "q": "best running shoes",
    "gl": "us", "hl": "en",
    "location": null, "device": "desktop",
    "num": 10, "page": 1,
    "freshness": "fresh", "enrichments": []
  },
  "organic_results": [
    {
      "position": 1,
      "title": "The 12 Best Running Shoes of 2026",
      "link": "https://example.com/best-running-shoes",
      "displayed_link": "example.com › running",
      "snippet": "Our lab-tested picks for road and trail..."
    }
  ],
  "people_also_ask": [
    { "question": "Which running shoe brand is best?" }
  ],
  "related_searches": [ { "query": "best trail running shoes" } ],
  "knowledge_graph": null
}

SERP · Google News

Google News results for a query — ranked articles with source, publish date and thumbnail.

POST/v1/news

Run a Google News query.

Scope: read
Cost: 1 credit (base) × freshness multiplier

Request body

Field	Type	Req.	Description
q	string	yes	Search query (1–400 chars).
gl / hl / location	string	no	Locale controls, as in /v1/search.
freshness	enum	no	"cached" \| "fresh" \| "live". Default "fresh".

Example request

cURL

curl -X POST https://api.dataswap.io/v1/news \
  -H "Authorization: Bearer sk_live_9f2c...4b1a" \
  -H "Content-Type: application/json" \
  -d '{ "q": "electric vehicles", "gl": "us", "hl": "en" }'

Example response

200 OK

{
  "search_metadata": { "engine": "google_news", "credits_used": 1, "cached": false, "...": "..." },
  "search_parameters": { "q": "electric vehicles", "gl": "us", "hl": "en" },
  "organic_results": [],
  "news_results": [
    {
      "position": 1,
      "title": "New EV tax credits take effect",
      "link": "https://news.example.com/ev-credits",
      "source": "Example Times",
      "date": "2026-07-19T22:00:00Z",
      "snippet": "The updated incentives apply to..."
    }
  ]
}

SERP · Google Maps

Local pack / Google Maps results — businesses with address, rating, reviews and phone.

POST/v1/maps

Run a Google Maps / local query.

Scope: read
Cost: 2 credits (base) × freshness multiplier

Request body

Field	Type	Req.	Description
q	string	yes	Local query, e.g. "coffee near me".
gl / hl / location	string	no	Locale controls, as in /v1/search.

Example request

cURL

curl -X POST https://api.dataswap.io/v1/maps \
  -H "Authorization: Bearer sk_live_9f2c...4b1a" \
  -H "Content-Type: application/json" \
  -d '{ "q": "auto parts", "location": "Lisbon,Portugal" }'

Example response

200 OK

{
  "search_metadata": { "engine": "google_maps", "credits_used": 2, "...": "..." },
  "search_parameters": { "q": "auto parts", "location": "Lisbon,Portugal" },
  "organic_results": [],
  "local_results": [
    {
      "position": 1,
      "title": "TelePeças Lisboa",
      "place_id": "ChIJ...",
      "address": "Av. da República 12, Lisboa",
      "rating": 4.6, "reviews": 318,
      "type": "Auto parts store",
      "phone": "+351 21 000 0000"
    }
  ]
}

Keywords Data

Google Ads search volume, CPC and competition for up to 100 keywords, with 12 months of history.

POST/v1/keywords

Get search volume, CPC and competition for a batch of keywords.

Scope: read
Cost: 3 credits (base)

Request body

Field	Type	Req.	Description
keywords	string[]	yes	Array of 1–100 keywords (≤80 chars each).
gl	string	no	Country, e.g. "us", "pt". Default "us". Ignored when location is set.
hl	string	no	Language, e.g. "en". Default "en".
location	string	no	Explicit location name, e.g. "Lisbon,Portugal".

Example request

cURL

curl -X POST https://api.dataswap.io/v1/keywords \
  -H "Authorization: Bearer sk_live_9f2c...4b1a" \
  -H "Content-Type: application/json" \
  -d '{ "keywords": ["running shoes", "trail shoes"], "gl": "us" }'

Example response

200 OK

{
  "search_metadata": { "engine": "keywords_google_ads", "credits_used": 3, "...": "..." },
  "search_parameters": { "keywords": ["running shoes","trail shoes"], "gl": "us", "hl": "en", "location": null },
  "keywords": [
    {
      "keyword": "running shoes",
      "search_volume": 165000,
      "cpc": 0.94,
      "competition": "HIGH",
      "competition_index": 88,
      "low_top_of_page_bid": 0.42,
      "high_top_of_page_bid": 1.71,
      "monthly_searches": [ { "year": 2026, "month": 6, "search_volume": 165000 } ]
    }
  ]
}

Labs

The intelligence layer: what a domain ranks for, and who its organic competitors are.

POST/v1/labs/ranked-keywords

Keywords a domain ranks for, with position, volume and estimated traffic value.

Scope: read
Cost: 4 credits (base)

Request body

Field	Type	Req.	Description
target	string	yes	Target domain, e.g. "telepecas.com".
gl / hl / location	string	no	Locale controls.
limit	integer	no	Max results (1–1000). Default 50.

Example request

cURL

curl -X POST https://api.dataswap.io/v1/labs/ranked-keywords \
  -H "Authorization: Bearer sk_live_9f2c...4b1a" \
  -H "Content-Type: application/json" \
  -d '{ "target": "telepecas.com", "gl": "pt", "limit": 50 }'

Example response

200 OK

{
  "search_metadata": { "engine": "labs_ranked_keywords", "credits_used": 4, "...": "..." },
  "search_parameters": { "target": "telepecas.com", "gl": "pt", "hl": "en", "location": null, "limit": 50 },
  "target": "telepecas.com",
  "total_count": 12480,
  "ranked_keywords": [
    {
      "keyword": "pastilhas travão",
      "search_volume": 2400, "cpc": 0.31, "competition": 0.42,
      "rank_group": 2, "rank_absolute": 2,
      "url": "https://telepecas.com/travagem", "etv": 512.4
    }
  ]
}

POST/v1/labs/competitors

Domains competing with the target in organic SERPs.

Scope: read
Cost: 4 credits (base)

Request body

Field	Type	Req.	Description
target	string	yes	Target domain.
gl / hl / location	string	no	Locale controls.
limit	integer	no	Max competitors (1–1000). Default 50.

Example request

cURL

curl -X POST https://api.dataswap.io/v1/labs/competitors \
  -H "Authorization: Bearer sk_live_9f2c...4b1a" \
  -H "Content-Type: application/json" \
  -d '{ "target": "telepecas.com", "gl": "pt" }'

Example response

200 OK

{
  "search_metadata": { "engine": "labs_competitors", "credits_used": 4, "...": "..." },
  "search_parameters": { "target": "telepecas.com", "gl": "pt", "hl": "en", "location": null, "limit": 50 },
  "target": "telepecas.com",
  "competitors": [
    {
      "domain": "b-parts.com",
      "avg_position": 6.2, "intersections": 842,
      "organic_count": 38200, "organic_etv": 145820.5
    }
  ]
}

Amazon Products

Amazon marketplace product data for a search term — price, rating, ASIN, best-seller flags.

POST/v1/amazon/products

Products for an Amazon search term.

Scope: read
Cost: 3 credits (base)

Request body

Field	Type	Req.	Description
keyword	string	yes	Amazon search term, e.g. "brake pads".
se_domain	string	no	Marketplace: "amazon.com" (default), "amazon.es", "amazon.co.uk"...

Example request

cURL

curl -X POST https://api.dataswap.io/v1/amazon/products \
  -H "Authorization: Bearer sk_live_9f2c...4b1a" \
  -H "Content-Type: application/json" \
  -d '{ "keyword": "brake pads", "se_domain": "amazon.com" }'

Example response

200 OK

{
  "search_metadata": { "engine": "amazon_products", "credits_used": 3, "...": "..." },
  "search_parameters": { "keyword": "brake pads", "se_domain": "amazon.com", "location_code": 2840 },
  "products": [
    {
      "rank": 1, "asin": "B08XYZ1234",
      "title": "Bosch QuietCast Premium Brake Pads",
      "price_from": 34.99, "price_to": null, "currency": "USD",
      "rating": 4.7, "reviews_count": 12840,
      "is_amazon_choice": true, "is_best_seller": false,
      "bought_past_month": 5000
    }
  ]
}

Backlinks

Backlink profile of a domain — link counts, referring domains, rank and spam score.

POST/v1/backlinks/summary

Aggregate backlink metrics for a domain or URL.

Scope: read
Cost: 5 credits (base)

Request body

Field	Type	Req.	Description
target	string	yes	Domain or URL, e.g. "telepecas.com".

Example request

cURL

curl -X POST https://api.dataswap.io/v1/backlinks/summary \
  -H "Authorization: Bearer sk_live_9f2c...4b1a" \
  -H "Content-Type: application/json" \
  -d '{ "target": "telepecas.com" }'

Example response

200 OK

{
  "search_metadata": { "engine": "backlinks_summary", "credits_used": 5, "...": "..." },
  "search_parameters": { "target": "telepecas.com" },
  "summary": {
    "target": "telepecas.com",
    "rank": 421,
    "backlinks": 184520,
    "referring_domains": 2140,
    "referring_main_domains": 1980,
    "broken_backlinks": 3120,
    "backlinks_spam_score": 12,
    "first_seen": "2018-03-11T00:00:00Z",
    "referring_links_tld": { "pt": 1440, "com": 520 }
  }
}

Business Data

Google My Business profile for a business — rating, reviews, category, contacts and coordinates.

POST/v1/business/info

Google My Business profile for a business query.

Scope: read
Cost: 2 credits (base)

Request body

Field	Type	Req.	Description
keyword	string	yes	Business name / query, e.g. "IKEA Alfragide".
gl / hl / location	string	no	Locale controls.

Example request

cURL

curl -X POST https://api.dataswap.io/v1/business/info \
  -H "Authorization: Bearer sk_live_9f2c...4b1a" \
  -H "Content-Type: application/json" \
  -d '{ "keyword": "IKEA Alfragide", "gl": "pt" }'

Example response

200 OK

{
  "search_metadata": { "engine": "business_info", "credits_used": 2, "...": "..." },
  "search_parameters": { "keyword": "IKEA Alfragide", "gl": "pt", "hl": "en", "location": null },
  "business": {
    "title": "IKEA Alfragide",
    "category": "Furniture store",
    "address": "Alfragide, Portugal",
    "phone": "+351 21 000 0000",
    "rating": 4.3, "reviews_count": 48210,
    "is_claimed": true,
    "latitude": 38.7223, "longitude": -9.2100
  }
}

On-Page

Technical SEO audit of a domain — on-page score, links, broken links, duplicates and checks.

POST/v1/onpage/summary

Crawl a domain and return an on-page audit summary.

Scope: read
Cost: 4 credits (base)

Request body

Field	Type	Req.	Description
target	string	yes	Domain to audit, e.g. "telepecas.com".
max_crawl_pages	integer	no	Pages to crawl (1–100). Default 10. More pages = slower.

Example request

cURL

curl -X POST https://api.dataswap.io/v1/onpage/summary \
  -H "Authorization: Bearer sk_live_9f2c...4b1a" \
  -H "Content-Type: application/json" \
  -d '{ "target": "telepecas.com", "max_crawl_pages": 10 }'

Example response

200 OK

{
  "search_metadata": { "engine": "onpage_summary", "credits_used": 4, "...": "..." },
  "search_parameters": { "target": "telepecas.com", "max_crawl_pages": 10 },
  "summary": {
    "target": "telepecas.com",
    "crawl_progress": "finished",
    "onpage_score": 92.4,
    "pages_crawled": 10, "total_pages": 10,
    "links_internal": 480, "links_external": 42,
    "broken_links": 3, "duplicate_title": 1, "duplicate_content": 0,
    "checks": { "no_description": 2, "large_page_size": 1 }
  }
}

Domain Analytics

Technology stack and metadata of a domain — detected tech, rank, contacts and social links.

POST/v1/domain/technologies

Technology stack and metadata for a domain.

Scope: read
Cost: 3 credits (base)

Request body

Field	Type	Req.	Description
target	string	yes	Domain to analyse, e.g. "telepecas.com".

Example request

cURL

curl -X POST https://api.dataswap.io/v1/domain/technologies \
  -H "Authorization: Bearer sk_live_9f2c...4b1a" \
  -H "Content-Type: application/json" \
  -d '{ "target": "telepecas.com" }'

Example response

200 OK

{
  "search_metadata": { "engine": "domain_technologies", "credits_used": 3, "...": "..." },
  "search_parameters": { "target": "telepecas.com" },
  "domain": {
    "domain": "telepecas.com",
    "domain_rank": 512,
    "title": "TelePeças — Peças Auto Online",
    "country_iso_code": "PT", "language_code": "pt",
    "emails": ["geral@telepecas.com"],
    "technologies": ["Nginx", "Next.js", "Cloudflare", "Stripe"]
  }
}

Content Analysis

Web mentions and citations of a keyword or brand — brand monitoring across the web.

POST/v1/content/search

Mentions / citations of a keyword across the web.

Scope: read
Cost: 5 credits (base)

Request body

Field	Type	Req.	Description
keyword	string	yes	Term / brand to monitor, e.g. "telepecas".
page_size	integer	no	Mentions to return (1–100). Default 10.

Example request

cURL

curl -X POST https://api.dataswap.io/v1/content/search \
  -H "Authorization: Bearer sk_live_9f2c...4b1a" \
  -H "Content-Type: application/json" \
  -d '{ "keyword": "telepecas", "page_size": 10 }'

Example response

200 OK

{
  "search_metadata": { "engine": "content_search", "credits_used": 5, "...": "..." },
  "search_parameters": { "keyword": "telepecas" },
  "total_count": 214,
  "mentions": [
    {
      "url": "https://blog.example.com/review-telepecas",
      "domain": "blog.example.com",
      "domain_rank": 340, "spam_score": 4,
      "title": "Comprei peças na TelePeças — a minha experiência",
      "snippet": "O envio foi rápido e...",
      "date_published": "2026-06-30T00:00:00Z"
    }
  ]
}

App Data

Google Play app search — apps with rating, developer, price and store URL.

POST/v1/apps/search

Search apps on Google Play.

Scope: read
Cost: 3 credits (base)

Request body

Field	Type	Req.	Description
keyword	string	yes	Search term, e.g. "car parts".
gl / hl	string	no	Locale controls.

Example request

cURL

curl -X POST https://api.dataswap.io/v1/apps/search \
  -H "Authorization: Bearer sk_live_9f2c...4b1a" \
  -H "Content-Type: application/json" \
  -d '{ "keyword": "car parts", "gl": "us" }'

Example response

200 OK

{
  "search_metadata": { "engine": "app_search", "credits_used": 3, "...": "..." },
  "search_parameters": { "keyword": "car parts", "gl": "us", "hl": "en" },
  "apps": [
    {
      "rank": 1, "app_id": "com.example.parts",
      "title": "Car Parts Finder",
      "developer": "Example Auto",
      "rating": 4.5, "reviews_count": 21400,
      "price": 0, "currency": "USD", "is_free": true,
      "url": "https://play.google.com/store/apps/details?id=com.example.parts"
    }
  ]
}

Batch

Submit up to 100 SERP queries in a single job and poll for results asynchronously.

POST/v1/batch

Create and start a batch of up to 100 SERP queries.

Scope: read
Cost: Sum of the per-query SERP costs

Request body

Field	Type	Req.	Description
queries	object[]	yes	Array of 1–100 query objects (same fields as /v1/search, plus optional per-query "engine").
engine	enum	no	Default engine for queries: "google_search" \| "google_news" \| "google_maps".

Example request

cURL

curl -X POST https://api.dataswap.io/v1/batch \
  -H "Authorization: Bearer sk_live_9f2c...4b1a" \
  -H "Content-Type: application/json" \
  -d '{
    "engine": "google_search",
    "queries": [
      { "q": "running shoes" },
      { "q": "trail shoes", "engine": "google_news" }
    ]
  }'

Example response

200 OK

{
  "id": "batch_01HZ...",
  "status": "queued",
  "total": 2,
  "completed": 0,
  "created_at": "2026-07-20T10:20:00Z"
}

GET/v1/batch/{id}

Poll a batch job for progress and results.

Scope: read
Cost: Free (status poll)

Request body

Field	Type	Req.	Description
id	string (path)	yes	Batch id returned by POST /v1/batch.

Example request

cURL

curl https://api.dataswap.io/v1/batch/batch_01HZ... \
  -H "Authorization: Bearer sk_live_9f2c...4b1a"

Example response

200 OK

{
  "id": "batch_01HZ...",
  "status": "completed",
  "total": 2, "completed": 2,
  "results": [
    { "q": "running shoes", "engine": "google_search", "status": "success", "credits_used": 1 },
    { "q": "trail shoes", "engine": "google_news", "status": "success", "credits_used": 1 }
  ]
}

Account & Platform

Manage credits, usage, the live price book and your API keys programmatically.

GET/v1/usage

Credit balance and recent usage for your account.

Scope: read
Cost: Free

Request body

No parameters.

Example request

cURL

curl https://api.dataswap.io/v1/usage \
  -H "Authorization: Bearer sk_live_9f2c...4b1a"

Example response

200 OK

{
  "credits_remaining": 9842,
  "credits_used_30d": 1580,
  "requests_30d": 640,
  "by_operation": { "search": 420, "labs_ranked_keywords": 60 }
}

GET/v1/pricing

Current price book — credit cost per operation, and whether that price is fixed or varies with the size of the request.

Scope: read
Cost: Free

Request body

No parameters.

Example request

cURL

curl https://api.dataswap.io/v1/pricing \
  -H "Authorization: Bearer sk_live_9f2c...4b1a"

Example response

200 OK

{
  "pricing": [
    { "operation": "search", "credits": 1, "credit_unit_usd": 0.01, "synced_at": "2026-07-20T00:00:00Z" },
    { "operation": "backlinks_summary", "credits": 5, "credit_unit_usd": 0.01, "synced_at": "2026-07-20T00:00:00Z" }
  ]
}

POST/v1/keys

Create a new API key. Returns the plaintext secret once — store it now.

Scope: admin
Cost: Free

Request body

Field	Type	Req.	Description
name	string	yes	Human label for the key (1–80 chars).
scopes	string[]	no	Subset of ["read","track","admin"]. Default ["read"].
mode	enum	no	"live" \| "test". Test keys never spend real credits.

Example request

cURL

curl -X POST https://api.dataswap.io/v1/keys \
  -H "Authorization: Bearer sk_live_9f2c...4b1a" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Production server", "scopes": ["read"], "mode": "live" }'

Example response

200 OK

{
  "id": "key_01HZ...",
  "name": "Production server",
  "secret": "sk_live_9f2c...4b1a",
  "scopes": ["read"],
  "mode": "live",
  "created_at": "2026-07-20T10:25:00Z"
}

GET/v1/keys

List your API keys (secrets are never returned again).

Scope: admin
Cost: Free

Request body

No parameters.

Example request

cURL

curl https://api.dataswap.io/v1/keys \
  -H "Authorization: Bearer sk_live_9f2c...4b1a"

Example response

200 OK

[
  { "id": "key_01HZ...", "name": "Production server", "scopes": ["read"], "mode": "live", "last_used_at": "2026-07-20T10:24:00Z" }
]

DELETE/v1/keys/{id}

Revoke an API key immediately.

Scope: admin
Cost: Free

Request body

Field	Type	Req.	Description
id	string (path)	yes	Id of the key to revoke.

Example request

cURL

curl -X DELETE https://api.dataswap.io/v1/keys/key_01HZ... \
  -H "Authorization: Bearer sk_live_9f2c...4b1a"

Example response

200 OK

{ "id": "key_01HZ...", "revoked": true }

AI Tools

Twelve tools that turn SERP and content data into answers, briefs and rankings — grounded in sources you can cite, not free-form generation. Flat price per call, no freshness multiplier.

POST/v1/ai/answer

Answer a question from SERP sources, with [n] citations back to each source.

Scope: read
Cost: 2 credits with your own sources · 4 if the API fetches the SERP

Request body

Field	Type	Req.	Description
query	string	yes	The question to answer (2–500 chars).
sources	array	no	Sources to ground the answer on ({ title, url, snippet }). Omit and the API runs the search itself — that is the 4-credit path.
max_words	integer	no	Length ceiling for the answer (20–400).
language	string	no	Output language, e.g. "en".
gl	string	no	Search country, used only when the API fetches the SERP.
num	integer	no	How many results to ground on when the API fetches the SERP (1–20).

Example request

cURL

curl -X POST https://api.dataswap.io/v1/ai/answer \
  -H "Authorization: Bearer sk_live_9f2c...4b1a" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "what changed in core web vitals in 2026",
    "max_words": 150
  }'

Example response

200 OK

{
  "answer": "INP replaced FID as the responsiveness metric [1], and the
             threshold for a \"good\" score is now 200ms [2].",
  "citations": [
    { "n": 1, "url": "https://example.com/cwv-2026", "title": "Core Web Vitals in 2026" },
    { "n": 2, "url": "https://example.org/inp", "title": "Understanding INP" }
  ],
  "credits_used": 4,
  "request_id": "req_01HZX8..."
}

POST/v1/ai/rerank

Reorder a document set by relevance to a query — the cheapest tool, built for RAG pipelines.

Scope: read
Cost: 1 credit

Request body

Field	Type	Req.	Description
query	string	yes	The query to rank against (1–2000 chars).
documents	string[]	yes	Documents to reorder (1–512).

Example request

cURL

curl -X POST https://api.dataswap.io/v1/ai/rerank \
  -H "Authorization: Bearer sk_live_9f2c...4b1a" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "how do I rotate an API key",
    "documents": [
      "Billing is prepaid and credits never expire.",
      "To rotate a key, create a new one, switch traffic, then revoke the old.",
      "Rate limits are applied per key on a one-minute window."
    ]
  }'

Example response

200 OK

{
  "results": [
    { "index": 1, "score": 0.94 },
    { "index": 2, "score": 0.21 },
    { "index": 0, "score": 0.08 }
  ],
  "credits_used": 1,
  "request_id": "req_01HZX8..."
}

Catalog Extraction

Point it at a store and get its products as structured JSON. Discovers product pages from the sitemap (falling back to the links on the page you submit) and extracts each one. Always asynchronous, and billed per product actually produced.

POST/v1/extract/catalog

Start a catalog extraction. Returns 202 with a job id — poll it for the result.

Scope: read
Cost: 1 credit per product extracted (max_products is reserved, then refunded to the real count)

Request body

Field	Type	Req.	Description
url	string	yes	The http(s) URL of the store, or the page to start discovery from.
max_products	integer	yes	Ceiling on products to extract (1–1000). This is what gets reserved up front.

Example request

cURL

curl -X POST https://api.dataswap.io/v1/extract/catalog \
  -H "Authorization: Bearer sk_live_9f2c...4b1a" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example-store.com/",
    "max_products": 50
  }'

Example response

200 OK

{
  "job_id": "3c9a1f28-7d64-4e0b-9a12-88b7c1d4e5f6",
  "status": "queued",
  "max_products": 50,
  "estimated_credits": 50
}

GET/v1/extract/catalog/{jobId}

Poll an extraction. The product document appears once status is "completed".

Scope: read
Cost: Free

Request body

Field	Type	Req.	Description
jobId	string (path)	yes	The job id returned by the 202.

Example request

cURL

curl https://api.dataswap.io/v1/extract/catalog/3c9a1f28-7d64-4e0b-9a12-88b7c1d4e5f6 \
  -H "Authorization: Bearer sk_live_9f2c...4b1a"

Example response

200 OK

{
  "job_id": "3c9a1f28-7d64-4e0b-9a12-88b7c1d4e5f6",
  "status": "completed",
  "url": "https://example-store.com/",
  "max_products": 50,
  "products_found": 128,
  "products_extracted": 50,
  "credits_charged": 50,
  "result": {
    "site": "example-store.com",
    "products": [
      { "url": "https://example-store.com/p/1", "title": "Trail Runner GTX",
        "price": "129.90", "currency": "EUR", "availability": "in_stock" }
    ],
    "generated_at": "2026-07-28T09:13:48.000Z"
  }
}

Reference

Full API reference

Every endpoint, grouped. All data endpoints require the read scope and are authenticated with your API key. The exact credit cost per operation is returned by GET /v1/pricing.

Search & SERP

POST	/v1/search	Google organic SERP (organic, ads, PAA, knowledge graph).
POST	/v1/news	Google News results for a query.
POST	/v1/maps	Google Maps / local pack results.
POST	/v1/autocomplete	Google autocomplete suggestions.
POST	/v1/images	Google Images results.
POST	/v1/shopping	Google Shopping product results.
POST	/v1/paa	People-Also-Ask questions for a query.
POST	/v1/bing/search	Bing organic SERP.

AI on the SERP

POST	/v1/serp/ai-overview	AI Overview for a query (text + references) plus organic results.
POST	/v1/serp/ai-mode	AI Mode answer with references.
POST	/v1/ai/llm-responses	Query an LLM (ChatGPT, Claude, Gemini, Perplexity) for AI-visibility analysis.

AI Tools

POST	/v1/ai/answer	Grounded answer with [n] citations. Pass your own sources, or let the API fetch the SERP first (4 credits). · 2–4 credits
POST	/v1/ai/content-brief	Content brief from the top of the SERP — angles, sections, entities to cover. · 3 credits
POST	/v1/ai/visibility	Whether and how a brand shows up in AI engine answers (GEO), against competitors. · 3 credits
POST	/v1/ai/serp-diff-explain	Explains why rankings moved and what to do next, from a rank diff. · 2 credits
POST	/v1/ai/competitor-brief	Competitive brief from a SERP — who ranks, on what, and where the gaps are. · 3 credits
POST	/v1/ai/review-summary	Review digest: recurring themes, sentiment and concrete actions. · 3 credits
POST	/v1/ai/keyword-cluster	Clusters a keyword list by topic and intent. · 2 credits
POST	/v1/ai/serp-intent	Search intent classification plus the SERP features that signal it. · 2 credits
POST	/v1/ai/content-gap	Topics competitors cover and you do not. · 3 credits
POST	/v1/ai/paa-expand	Expands People-Also-Ask questions into grounded answers. · 2 credits
POST	/v1/ai/summarize	Multi-document summary with citations back to the source documents. · 2 credits
POST	/v1/ai/rerank	Reorders up to 512 documents by relevance to a query. · 1 credits

Jobs & extraction

GET	/v1/jobs/:id	Poll a long-running operation handed off with 202 — see “Long-running jobs”.
POST	/v1/extract/catalog	Start an e-commerce catalog extraction. Billed per product produced.
GET	/v1/extract/catalog/:jobId	Poll a catalog extraction and collect the product document.

SERP tracking

POST

/v1/serp-diff

Track SERP changes over time — rank deltas (added/removed/moved) vs your last snapshot.

YouTube

POST	/v1/youtube/search	YouTube search (videos, channels, playlists).
POST	/v1/youtube/video	Rich metadata for a single video.
POST	/v1/youtube/comments	Comments for a video.
POST	/v1/youtube/subtitles	Transcript / subtitles for a video (optional translation).

Trends

POST

/v1/trends

Google Trends — interest over time, by region, related topics & queries.

Keywords

POST	/v1/keywords	Search volume, CPC and competition for keywords.
POST	/v1/keywords/for-site	Keyword ideas a domain ranks for.
POST	/v1/keywords/search-volume	Search volume for a keyword list.
POST	/v1/keywords/for-keywords	Keyword ideas seeded from keywords.
POST	/v1/keywords/clickstream-volume	Clickstream-based search volume.
POST	/v1/keywords/clickstream-global	Global clickstream search volume.

Labs — SEO intelligence

POST	/v1/labs/ranked-keywords	Keywords a domain ranks for.
POST	/v1/labs/competitors	Organic competitors for a domain.
POST	/v1/labs/search-intent	Search-intent classification for keywords.
POST	/v1/labs/keyword-ideas	Keyword ideas for seed keywords.
POST	/v1/labs/keyword-suggestions	Long-tail suggestions for a keyword.
POST	/v1/labs/related-keywords	Related keywords (depth-based).
POST	/v1/labs/keyword-difficulty	Keyword difficulty scores.
POST	/v1/labs/keyword-overview	Full metrics overview for keywords.
POST	/v1/labs/historical-search-volume	Historical search volume.
POST	/v1/labs/domain-rank-overview	Domain rank / traffic overview.
POST	/v1/labs/historical-rank-overview	Historical domain rank overview.
POST	/v1/labs/domain-intersection	Keywords two domains both rank for.
POST	/v1/labs/relevant-pages	Top pages of a domain by traffic.
POST	/v1/labs/bulk-traffic-estimation	Traffic estimates for many domains.

Backlinks

POST	/v1/backlinks/summary	Backlink profile summary for a target.
POST	/v1/backlinks/list	Individual backlinks for a target.
POST	/v1/backlinks/anchors	Anchor-text distribution.
POST	/v1/backlinks/referring-domains	Referring domains.
POST	/v1/backlinks/competitors	Backlink competitors.
POST	/v1/backlinks/domain-intersection	Domains linking to multiple targets.
POST	/v1/backlinks/page-intersection	Pages linking to multiple targets.
POST	/v1/backlinks/history	Historical backlink metrics.
POST	/v1/backlinks/timeseries-summary	Backlink metrics over time.
POST	/v1/backlinks/domain-pages	Pages of a domain with backlink data.
POST	/v1/backlinks/domain-pages-summary	Summary of a domain’s pages.
POST	/v1/backlinks/bulk-ranks	Rank for many targets.
POST	/v1/backlinks/bulk-backlinks	Backlink counts for many targets.
POST	/v1/backlinks/bulk-spam-score	Spam scores for many targets.
POST	/v1/backlinks/bulk-referring-domains	Referring-domain counts for many targets.
POST	/v1/backlinks/bulk-new-lost-backlinks	New/lost backlinks for many targets.
POST	/v1/backlinks/bulk-new-lost-referring-domains	New/lost referring domains for many targets.

On-Page

POST	/v1/onpage/summary	On-page SEO summary for a crawl.
POST	/v1/onpage/instant	Instant single-page audit (no crawl).
POST	/v1/onpage/content-parsing	Parse a page’s content structure.
POST	/v1/onpage/crawl	Start a site crawl → returns a task_id.
POST	/v1/onpage/pages	Crawled pages (by task_id).
POST	/v1/onpage/links	Internal/external links (by task_id).
POST	/v1/onpage/resources	Page resources (by task_id).
POST	/v1/onpage/duplicate-tags	Duplicate title/description/H1 (by task_id).
POST	/v1/onpage/lighthouse	Lighthouse performance audit for a URL.

Content analysis

POST	/v1/content/search	Search citations/mentions across the web.
POST	/v1/content/summary	Aggregate content summary for a keyword.
POST	/v1/content/sentiment	Sentiment analysis of mentions.
POST	/v1/content/rating-distribution	Rating distribution for a topic.
POST	/v1/content/category-trends	Category trend analysis.

Amazon

POST	/v1/amazon/products	Amazon product search results.
POST	/v1/amazon/asin	Product detail by ASIN.
POST	/v1/amazon/sellers	Sellers for a product.
POST	/v1/amazon/reviews	Reviews for a product.

Business & Reviews

POST	/v1/business/info	Google Business profile info.
POST	/v1/business/my-business-updates	Business posts / updates.
POST	/v1/business/questions-and-answers	Q&A on a business profile.
POST	/v1/business/hotel-searches	Hotel search results.
POST	/v1/business/hotel-info	Hotel detail info.
POST	/v1/business/listings/search	Search business listings by category / location.
POST	/v1/business/listings/categories	Category aggregation for listings.
POST	/v1/reviews/google	Google reviews for a business.
POST	/v1/reviews/trustpilot	Trustpilot reviews for a domain.
POST	/v1/reviews/tripadvisor	Tripadvisor reviews.
POST	/v1/search/trustpilot	Search Trustpilot businesses.
POST	/v1/search/tripadvisor	Search Tripadvisor entities.

Domain

POST	/v1/whois	WHOIS + domain overview.
POST	/v1/domain/technologies	Technology-stack detection for a domain.

App data

POST

/v1/apps/search

Google Play app search.

Batch & account

POST	/v1/batch	Submit multiple queries in one request.
GET	/v1/batch/:id	Fetch a batch result by id.
GET	/v1/usage	Your usage stats and recent activity.
GET	/v1/pricing	Current price book — credits per operation.

Ready to build?

Create an account to get your API key, buy credits, and start with POST /v1/search.

Get your key Talk to us