Skip to content

docs: recommend several example URLs of one page type for prepare_domain() #68

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jonathan-zenrows merged 2 commits into from
Oct 27, 2026
Merged

docs: recommend several example URLs of one page type for prepare_domain() #68

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
fd0abc7
docs: recommend several example URLs of one page type for prepare_dom…
zenrows-dev-pool[bot] Oct 21, 2026
a821d8a
docs: align prepare_domain() example URL guidance with the canonical …
zenrows-dev-pool[bot] Oct 26, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 9 additions & 2 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -229,7 +229,9 @@ The legacy `402` with `code: "AUTH010"` means the domain isn't enabled. `extract

#### Preparing a domain

`client.prepare_domain(domain, example_urls)` submits a domain for Extract (`POST /v1/extract/prepared-domains`), and `client.prepared_domain_status(domain)` reads where it is (`GET /v1/extract/prepared-domains/{domain}`). Both return the parsed status object. Pass the domain without a scheme and 1 to 5 example URLs, one per kind of page you want to extract. These calls cost no credits.
`client.prepare_domain(domain, example_urls)` submits a domain for Extract (`POST /v1/extract/prepared-domains`), and `client.prepared_domain_status(domain)` reads where it is (`GET /v1/extract/prepared-domains/{domain}`). Both return the parsed status object. Pass the domain without a scheme and 1 to 5 example URLs on it. These calls cost no credits.

One example URL works; we recommend 3 or more of the same page type (e.g. 3 product pages), because Extract compares pages of one type to check the fields it found and fill in fields one page is missing. Several page types can share the 5 (e.g. 3 product pages + 2 search-result pages).

Preparation takes minutes, and the client does not wait for it. Poll the status until it is no longer `"preparing"`:

Expand All @@ -243,7 +245,12 @@ client = ZenRowsClient("YOUR-API-KEY")
try:
status = client.prepare_domain(
"www.scrapingcourse.com",
["https://www.scrapingcourse.com/ecommerce/"],
[
# Three pages of one page type: product pages on the same domain.
"https://www.scrapingcourse.com/ecommerce/product/abominable-hoodie/",
"https://www.scrapingcourse.com/ecommerce/product/adrienne-trek-jacket/",
"https://www.scrapingcourse.com/ecommerce/product/aeon-capri/",
],
)
except PreparedDomainError as err:
# e.g. 409 in_progress, 429 out_of_allowance, 503 overloaded
Expand Down
6 changes: 5 additions & 1 deletion src/zenrows/client.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -325,7 +325,11 @@ def prepare_domain(self, domain: str, example_urls: list[str]) -> dict:
`ready` or `failed`), `state`, `submitted_at`, `updated_at`.

`domain` is the domain without a scheme. `example_urls` are 1 to 5
URLs on that domain, one per kind of page you want to extract.
URLs on that domain. One works; we recommend 3 or more of the same
page type (e.g. 3 product pages), because Extract compares pages of
one type to check the fields it found and fill in fields one page is
missing. Several page types can share the 5 (e.g. 3 product pages +
2 search-result pages).
Submitting a domain that is already prepared returns its current
status instead of starting a new run.

Expand Down
Loading