Official SDKs
Typed clients for Python and TypeScript: full API coverage, cursor iterators and typed errors.
Installation
Python
pip install scrapeadlibraryTypeScript
npm install scrapeadlibraryQuick 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.
| Python | TypeScript | Endpoint |
|---|---|---|
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
| Option | Default | Description |
|---|---|---|
api_key / apiKey | SCRAPEADLIBRARY_API_KEY | Your API key (starts with sal_) |
base_url / baseUrl | https://api.scrapeadlibrary.com | API base URL |
timeout | 30 s | Request timeout (seconds in Python, milliseconds in TypeScript) |
max_retries / maxRetries | 2 | Retries 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.