Official SDKs

Typed clients for Python and TypeScript: full API coverage, cursor iterators and typed errors.

Installation

Python

pip install scrapeadlibrary

TypeScript

npm install scrapeadlibrary

Quick Start

from scrapeadlibrary import ScrapeAdLibrary

client = ScrapeAdLibrary(api_key="sal_your_api_key")

# Search ads
result = client.ads.search(q="nike", country="IT")
for ad in result.data:
    print(ad.page.name, ad.started_at, ad.platforms)

# Ad detail with EU transparency data
ad = client.ads.get("1550534860016399")

# Advertiser page and its ads
page = client.pages.get("15087023444")
page_ads = client.pages.ads("15087023444", status="all")

# Advertisers that ran ads matching a keyword
pages = client.pages.search(q="running shoes")

Methods

Parameters have the names of the API (snake_case in Python, camelCase in TypeScript); methods return the JSON body of the response.

PythonTypeScriptEndpoint
client.ads.search(q=..., country=...)client.ads.search({ q, country })GET /v1/ads/search
client.ads.search_all(...)client.ads.searchAll({ ... })GET /v1/ads/search (all pages)
client.ads.get(ad_id)client.ads.get(adId)GET /v1/ads/{ad_id}
client.pages.get(page_id)client.pages.get(pageId)GET /v1/pages/{page_id}
client.pages.ads(page_id)client.pages.ads(pageId)GET /v1/pages/{page_id}/ads
client.pages.search(q=...)client.pages.search({ q })GET /v1/pages/search

Iterate Over All Results

The iterators follow next_cursor for you and fetch a page only when you need it. Set a maximum so a broad search does not spend more credits than you planned.

for ad in client.ads.search_all(q="nike", country="IT", status="all", max_items=1000):
    save(ad)

Async Support (Python)

import asyncio
from scrapeadlibrary import AsyncScrapeAdLibrary

async def main():
    async with AsyncScrapeAdLibrary(api_key="sal_your_api_key") as client:
        result = await client.ads.search(q="nike", country="IT")
        print(len(result.data), "ads")

asyncio.run(main())

Error Handling

Every API error raises a typed exception carrying the error code and the message of the response. Failed calls cost no credits.

from scrapeadlibrary import (
    ScrapeAdLibrary,
    ScrapeAdLibraryError,
    AuthenticationError,
    InsufficientCreditsError,
    NotFoundError,
    RateLimitError,
)

client = ScrapeAdLibrary(api_key="sal_your_api_key")

try:
    ad = client.ads.get("1550534860016399")
except NotFoundError:
    print("No such ad")
except InsufficientCreditsError:
    print("Out of credits")
except RateLimitError as e:
    print(f"Slow down, retry in {e.retry_after}s")
except AuthenticationError:
    print("Invalid API key")
except ScrapeAdLibraryError as e:
    print(e.code, e.message)

Credits

After any call, the client exposes the credits charged and the credits left, read from the X-Credits-Used and X-Credits-Remaining headers.

client.ads.search(q="nike")
print(client.credits_used, client.credits_remaining)

Configuration

OptionDefaultDescription
api_key / apiKeySCRAPEADLIBRARY_API_KEYYour API key (starts with sal_)
base_url / baseUrlhttps://api.scrapeadlibrary.comAPI base URL
timeout30 sRequest timeout (seconds in Python, milliseconds in TypeScript)
max_retries / maxRetries2Retries on 429, 500, 503 and 504, honouring Retry-After

Without explicit options the clients read SCRAPEADLIBRARY_API_KEY and SCRAPEADLIBRARY_BASE_URL from the environment.

How the SDKs Behave

Both SDKs are thin, typed wrappers around the REST API, so everything in the API reference applies to them. A few things they do for you are worth knowing before you put them in production:

  • Automatic retries. Rate limits (429) and temporary failures of the Ad Library (500, 503, 504) are retried with exponential backoff, waiting the number of seconds in the Retry-After header when the API sends one. A failed call costs no credits, so a retry never costs twice. A 502 upstream_schema_changed is not retried: it means the Ad Library changed and we are fixing the parser.
  • Typed errors. Every error code becomes its own exception or error class with the HTTP status, the stable error code, the message and the details, so you can catch “not found” separately from “out of credits”.
  • Pagination helpers. The iterators follow next_cursor for you and stop after the number of items you ask for, so a loop over thousands of ads never spends more credits than you planned.
  • Credit headers. After each call the client exposes the remaining balance read from X-Credits-Remaining, handy to stop a batch job before it runs dry.

Resources