diff --git a/README.md b/README.md index ff259f6..4c2e9ec 100644 --- a/README.md +++ b/README.md @@ -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"`: @@ -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 diff --git a/src/zenrows/client.py b/src/zenrows/client.py index bae8a5e..61df0c7 100644 --- a/src/zenrows/client.py +++ b/src/zenrows/client.py @@ -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.