# Allegro Product **GET** `https://api.piloterr.com/v2/allegro/product` Extract product details from Allegro, Poland's leading e-commerce platform, for insightful market analysis. **Credit cost:** 2 credits per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | URL of the Allegro product page to extract data from. **Accepted formats:** - `https://allegro.pl/ogloszenie/{slug}-{id}`: Standard product listing URL - `https://allegro.pl/oferta/{slug}-{id}`: Alternative offer URL format **Example:** https://allegro.pl/ogloszenie/obejmy-fi50-fi51-fi52-i-inne-obejma-uchwyty-slupek-11917354378 **Notes:** - **Inactive or removed listings** may return partial or empty data. - The offer ID at the end of the URL uniquely identifies the product. | ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "sku": { "type": "string" }, "url": { "type": "string" }, "bars": { "type": "array", "items": {} }, "icon": { "type": "string" }, "name": { "type": "string" }, "skin": { "type": "string" }, "type": { "type": "integer" }, "brand": { "nullable": true }, "image": { "type": "string" }, "offer": { "type": "object", "properties": { "id": { "type": "string" }, "seo": { "type": "object", "properties": { "title": { "type": "string" }, "noindex": { "type": "boolean" }, "nofollow": { "type": "boolean" }, "canonical": { "type": "object", "properties": { "url": { "type": "string" } } }, "description": { "type": "string" } } }, "name": { "type": "string" }, "view": { "type": "object", "properties": { "url": { "type": "string" }, "type": { "type": "string" }, "ended": { "nullable": true }, "future": { "nullable": true }, "snapshot": { "nullable": true }, "restricted": { "nullable": true } } }, "coins": { "nullable": true }, "stock": { "nullable": true }, "images": { "type": "array", "items": { "type": "object", "properties": { "alt": { "type": "string" }, "url": { "type": "string" } } } }, "seller": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "login": { "type": "string" }, "brand": { "type": "object", "properties": { "logotype": { "nullable": true }, "description": { "nullable": true } } }, "banner": { "nullable": true }, "company": { "type": "object", "properties": { "name": { "type": "string" }, "address": { "type": "object", "properties": { "city": { "type": "string" }, "street": { "type": "string" }, "country": { "type": "string" }, "zip_code": { "type": "string" }, "country_code": { "type": "string" } } }, "verified": { "type": "boolean" }, "representative_label": { "type": "string" }, "tax_identification_number": { "type": "string" }, "national_court_register_number": { "nullable": true }, "statistical_identification_number": { "type": "string" } } }, "contact": { "type": "object", "properties": { "emails": { "type": "array", "items": {} }, "phones": { "type": "array", "items": {} }, "open_hours": { "type": "array", "items": { "type": "object", "properties": { "days_label": { "type": "string" }, "hours_labels": { "type": "array", "items": { "type": "string" } }, "days_short_label": { "type": "string" } } } } } }, "listing": { "type": "object", "properties": { "url": { "type": "string" } } }, "logotype": { "nullable": true }, "vacation": { "nullable": true }, "descriptions": { "type": "object", "properties": { "main": { "nullable": true }, "additional": { "nullable": true } } }, "super_seller": { "nullable": true }, "privacy_policy": { "nullable": true }, "representation": { "nullable": true }, "category_listing": { "type": "object", "properties": { "url": { "type": "string" } } } } }, "charity": { "nullable": true }, "contact": { "type": "object", "properties": { "id": { "type": "string" }, "emails": { "type": "array", "items": { "type": "object", "properties": { "address": { "type": "string" } } } }, "phones": { "type": "array", "items": { "type": "object", "properties": { "number": { "type": "string" }, "number_label": { "type": "string" }, "number_label_masked": { "type": "string" } } } } } }, "product": { "type": "object", "properties": { "rating": { "nullable": true }, "reviews": { "nullable": true } } }, "rebates": { "type": "object", "properties": { "bundles": { "type": "array", "items": {} } } }, "category": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "tree": { "type": "string" } } }, "delivery": { "type": "object", "properties": { "summary": { "type": "array", "items": { "type": "object", "properties": { "icon": { "type": "object", "properties": { "id": { "type": "string" } } }, "name": { "type": "object", "properties": { "icon": { "nullable": true }, "text": { "type": "string" }, "featured": { "type": "boolean" } } }, "badge": { "nullable": true }, "value": { "type": "object", "properties": { "text": { "type": "string" }, "text_color": { "nullable": true }, "context_info": { "nullable": true } } }, "action": { "nullable": true }, "labels": { "type": "array", "items": {} } } } } } }, "location": { "type": "object", "properties": { "city": { "type": "string" }, "country": { "type": "string" }, "province": { "type": "string" }, "country_code": { "type": "string" } } }, "campaigns": { "type": "object", "properties": { "summary": { "type": "array", "items": {} } } }, "watchlist": { "type": "object", "properties": { "is_watched": { "type": "boolean" } } }, "automotive": { "type": "object", "properties": {} }, "info_boxes": { "type": "array", "items": {} }, "parameters": { "type": "array", "items": { "type": "object", "properties": { "id": { "nullable": true }, "name": { "type": "string" }, "values": { "type": "array", "items": { "type": "object", "properties": { "id": { "nullable": true }, "url": { "nullable": true }, "value_label": { "type": "string" } } } } } } }, "attachments": { "type": "array", "items": {} }, "breadcrumbs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" } } } }, "publication": { "type": "object", "properties": { "ended_at": { "nullable": true }, "ending_at": { "type": "string" }, "starting_at": { "nullable": true }, "availability": { "nullable": true } } }, "installments": { "nullable": true }, "selling_mode": { "type": "object", "properties": { "tax": { "nullable": true }, "cart": { "nullable": true }, "auction": { "nullable": true }, "buy_now": { "nullable": true }, "restricted": { "nullable": true }, "advertisement": { "type": "object", "properties": { "price": { "type": "object", "properties": { "amount": { "type": "string" }, "currency": { "type": "string" }, "before_exchange": { "nullable": true } } }, "price_prefix_label": { "nullable": true } } }, "one_click_buy": { "nullable": true } } }, "view_counter": { "nullable": true }, "product_series": { "nullable": true }, "parameters_groups": { "type": "object", "properties": { "title": { "type": "string" }, "groups": { "type": "array", "items": { "type": "object", "properties": { "icon": { "nullable": true }, "name": { "nullable": true }, "parameters": { "type": "array", "items": { "type": "object", "properties": { "id": { "nullable": true }, "name": { "type": "string" }, "values": { "type": "array", "items": { "type": "object", "properties": { "id": { "nullable": true }, "url": { "nullable": true }, "value_label": { "type": "string" } } } } } } }, "description": { "nullable": true } } } } } }, "assortment_category": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "assortment_category_path": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } } } } }, "price": { "type": "string" }, "route": { "type": "string" }, "title": { "type": "string" }, "erotic": { "type": "boolean" } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # Allegro Search **GET** `https://api.piloterr.com/v2/allegro/search` Search for products across Allegro, Poland's leading e-commerce marketplace, and retrieve structured product listings. **Credit cost:** 2 credits per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | Search keyword to look up products on Allegro, Poland's largest marketplace. **Example:** Karty pokemon **Notes:** - **Supports Polish characters** — diacritics such as `ż`, `ę`, `ó` are handled correctly. - Results may include sponsored and promoted listings alongside organic results. - The more specific your keyword, the more targeted the results. | ## Responses ### 200 Successful response ```json { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "image": { "type": "string" } } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # Amazon Product Offer **GET** `https://api.piloterr.com/v2/amazon/product/offer` Efficiently extract details of third-party seller offers for any Amazon product across multiple marketplaces. **Credit cost:** 1 credit per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | Amazon product ASIN (Amazon Standard Identification Number) to retrieve third-party seller offers for. **Example:** B093C9B1HK **Notes:** - **The ASIN is a 10-character alphanumeric code** visible in the product URL on Amazon (e.g. `amazon.com/dp/B093C9B1HK`). - Only products with active third-party offers will return results — products sold exclusively by Amazon may return an empty list. | | `domain` | query | `string` | No | Amazon domain extension to query. Controls which Amazon marketplace is targeted. - `com`: Amazon United States (default) - `fr`: Amazon France - `de`: Amazon Germany - `co.uk`: Amazon United Kingdom - `it`: Amazon Italy - `es`: Amazon Spain - `ca`: Amazon Canada - `co.jp`: Amazon Japan - `com.br`: Amazon Brazil - `com.mx`: Amazon Mexico - `in`: Amazon India | | `page` | query | `number` | No | Page number for paginated offer results. **Note:** Use this parameter to paginate through multiple pages of offers when a product has many third-party sellers. | ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "asin": { "type": "string" }, "price": { "type": "number" }, "seller_url": { "type": "string" }, "seller_name": { "type": "string" }, "delivery_info": { "type": "object", "properties": { "time": { "type": "string" }, "type": { "type": "string" }, "price": { "type": "string" } } }, "discount_percentage": { "type": "integer" } } } } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # Amazon Product **GET** `https://api.piloterr.com/v2/amazon/product` Efficiently extract product details from Amazon for dynamic retail insights, including price, stock, features, and seller data. **Credit cost:** 1 credit per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | Amazon product ASIN (Amazon Standard Identification Number) to retrieve full product details for. **Example:** B09DFCB66S **Notes:** - **The ASIN is a 10-character alphanumeric code** found in the Amazon product URL (e.g. `amazon.com/dp/B09DFCB66S`). - Each ASIN is unique to a specific product and marketplace. | | `domain` | query | `string` | No | Amazon domain extension to query. Controls which Amazon marketplace is targeted. - `com`: Amazon United States (default) - `fr`: Amazon France - `de`: Amazon Germany - `co.uk`: Amazon United Kingdom - `it`: Amazon Italy - `es`: Amazon Spain - `ca`: Amazon Canada - `co.jp`: Amazon Japan - `com.br`: Amazon Brazil - `com.mx`: Amazon Mexico - `in`: Amazon India | ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "url": { "type": "string" }, "asin": { "type": "string" }, "image": { "type": "string" }, "price": { "nullable": true }, "stock": { "type": "string" }, "title": { "type": "string" }, "coupon": { "nullable": true }, "images": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "type": { "type": "string" }, "width": { "type": "integer" }, "height": { "type": "integer" } } } }, "currency": { "nullable": true }, "features": { "type": "array", "items": { "type": "string" } }, "variants": { "type": "array", "items": {} }, "description": { "type": "string" }, "product_information": { "type": "object", "properties": { "asin": { "type": "string" }, "rated": { "type": "string" }, "batteries": { "type": "string" }, "item_weight": { "type": "string" }, "manufacturer": { "type": "string" }, "release_date": { "type": "string" }, "type_of_item": { "type": "string" }, "best_sellers_rank": { "type": "array", "items": { "type": "string" } }, "item_model_number": { "type": "string" }, "product_dimensions": { "type": "string" }, "date_first_available": { "type": "string" } } }, "merchant_information": { "nullable": true } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # Amazon Search **GET** `https://api.piloterr.com/v2/amazon/search` Efficiently scrape Amazon search results for real-time product data and insights across multiple Amazon marketplaces. **Credit cost:** 1 credit per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | Keyword or phrase to search for products on Amazon. **Example:** playstation 5 **Notes:** - Searches are performed against the marketplace set by the `domain` parameter. - Results include both organic and sponsored (ad) listings. - Combine with `page` to retrieve more results beyond the first page. | | `domain` | query | `string` | No | Amazon domain extension to query. Controls which Amazon marketplace is searched. - `com`: Amazon United States (default) - `fr`: Amazon France - `de`: Amazon Germany - `co.uk`: Amazon United Kingdom - `it`: Amazon Italy - `es`: Amazon Spain - `ca`: Amazon Canada - `co.jp`: Amazon Japan - `com.br`: Amazon Brazil - `com.mx`: Amazon Mexico - `in`: Amazon India | | `page` | query | `number` | No | Page number for paginated search results. Each page returns up to 60 results. | ## Responses ### 200 Successful response ```json { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "asin": { "type": "string" }, "price": { "nullable": true }, "title": { "type": "string" }, "rating": { "type": "number" }, "real_price": { "type": "number" }, "reviews_count": { "type": "integer" } } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # API Keys API keys authenticate your requests to the API. You manage them entirely from the dashboard: set a category, restrict usage with rolling quotas, add an expiry date, and monitor activity per key through request logs. For how to include a key in a request, see the [Introduction](/). Creating a key [#creating-a-key] Open the form [#open-the-form] Go to [dashboard → API Keys → New](https://app.piloterr.com). Fill in the fields [#fill-in-the-fields] Give the key an **alias** (unique label for your own reference), pick a **category**, and optionally configure quotas and an expiry date. Copy the secret [#copy-the-secret] After saving, the secret is shown **once**. Copy it immediately and store it in an environment variable. It cannot be retrieved again. Key fields [#key-fields] | Field | Description | | ------------------ | ------------------------------------------------------------------------------------------------ | | **Alias** | Unique label per account. Shows up in logs and dashboard filters. | | **Category** | Organizational tag (see [Categories](#categories)). Has no effect on API behavior. | | **Active** | Enables or disables the key. Inactive keys are rejected immediately with `401 Inactive API Key`. | | **Expires** | Optional date after which the key stops working. Leave blank for no expiry. | | **Request quotas** | Optional per-key caps on rolling time windows (see [Per-key quotas](#per-key-quotas)). | Categories [#categories] Categories tag keys for your own organization. They appear in dashboard filters and analytics but do not change how the API processes a request. | Category | Typical use | | ------------- | --------------------------------------------------- | | `production` | Live traffic, customer-facing systems | | `development` | Local development and testing | | `staging` | Pre-production and CI environments | | Custom | Any free-text label, e.g. `sandbox`, `partner-acme` | Keep one key per environment so you can revoke or rotate it independently. Per-key quotas [#per-key-quotas] Each key can have independent hard caps on request volume, enforced on rolling windows (not calendar boundaries): | Quota | Window | | ----------- | ----------------------------------------------------- | | **Total** | All-time: the key is blocked permanently once reached | | **Daily** | Last 24 hours (rolling, not midnight-to-midnight) | | **Weekly** | Last 7 days (rolling) | | **Monthly** | Last 30 days (rolling) | Leave a field blank to apply no cap for that window. When a quota is reached, the API returns `401 Rate Limit Exceeded` with the quota name in the message: ```json { "error": "Rate limit exceeded: quota total" } ``` ```json { "error": "Rate limit exceeded: quota daily" } ``` ```json { "error": "Rate limit exceeded: quota weekly" } ``` ```json { "error": "Rate limit exceeded: quota monthly" } ``` Quota counts are aggregated from request logs and cached for up to 24 hours. Enforcement is accurate within that window, not to the exact request. Per-key quotas are distinct from **plan-level rate limits** (per-second and per-minute caps that apply account-wide). Plan limits return `429 Too Many Requests`. See [Error Handling](/error-handling) for details. Expiry [#expiry] Set an expiry date on keys used in scripts, CI pipelines, or partner integrations. Once the date passes, the API returns: ```json { "error": "Expired API Key" } ``` HTTP status `401`. Create and deploy a replacement key before the expiry date to avoid any downtime. Request logs [#request-logs] Every request made with a key is recorded under **API Keys → Logs** in the dashboard. Each entry shows: | Field | Description | | -------- | -------------------------------- | | Endpoint | HTTP method and path | | Status | Response status code | | Duration | Time to first byte (ms) | | IP | Caller IP address | | Credits | Credits charged for this request | Use logs to audit activity per key, debug unexpected errors, or identify traffic from compromised keys. Deactivating vs. deleting [#deactivating-vs-deleting] | Action | Effect | | -------------- | ---------------------------------------------------------------------------------------------------- | | **Deactivate** | Key is blocked immediately. Usage history and settings are kept. Can be reactivated. | | **Delete** | Permanently removes the key and its configuration. Only possible if the key has **never been used**. | Prefer deactivation over deletion. If a key has request history, it cannot be deleted. The history is retained for billing and auditing. Rotating a key [#rotating-a-key] Create the replacement [#create-the-replacement] Go to [dashboard → API Keys → New](https://app.piloterr.com) and create a new key with the same category and quota settings. Give it a new alias to distinguish it. Deploy the new key [#deploy-the-new-key] Update the environment variable in every system that uses the old key and redeploy. Deactivate the old key [#deactivate-the-old-key] Set the old key to **inactive** in the dashboard. This blocks any remaining requests without removing its history. Error reference [#error-reference] | Error | Status | Cause | | ------------------------------------------------ | ------ | ---------------------------------------------- | | `Invalid API Key` | 401 | Key not found or malformed | | `Inactive API Key` | 401 | Key is disabled | | `Expired API Key` | 401 | Key has passed its expiry date | | `Rate limit exceeded: quota …` | 401 | Per-key rolling quota reached | | `exceeded the … rate limit on your subscription` | 429 | Plan-level per-second or per-minute cap | | `IP temporarily blocked` | 403 | Too many failed auth attempts from the same IP | *** See also: [Best Practices](/best-practices) for security guidelines and [Glossary](/glossary) for term definitions. # Auchan Product **GET** `https://api.piloterr.com/v2/auchan/product` Effortlessly extract product details from Auchan for dynamic business insights, including nutritional information, ingredients, ratings, and reviews. **Credit cost:** 2 credits per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | URL of the Auchan product page to extract data from. **Example:** https://www.auchan.fr/charles-alice-specialite-pommes-mangues-sans-sucres-ajoutes/pr-C1177497 **Notes:** - **Only auchan.fr product URLs are supported** URLs from other regional Auchan sites are not accepted. - The product reference code at the end of the URL (e.g. `pr-C1177497`) uniquely identifies the product. - Private or delisted products may return partial or no data. | ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "brand": { "type": "string" }, "image": { "type": "string" }, "title": { "type": "string" }, "rating": { "type": "integer" }, "features": { "type": "object", "properties": { "ean": { "type": "string" }, "contact": { "type": "object", "properties": { "exploitant": { "type": "string" }, "service_consommateur": { "type": "string" } } }, "reference": { "type": "string" }, "description": { "type": "string" }, "ingredients": { "type": "string" }, "pays_de_fabrication": { "type": "string" }, "valeurs_nutritionnelles": { "type": "object", "properties": { "sel": { "type": "string" }, "glucides": { "type": "string" }, "proteines": { "type": "string" }, "dont_sucres": { "type": "string" }, "matieres_grasses": { "type": "string" }, "fibres_alimentaires": { "type": "string" }, "valeur_energetique_kj": { "type": "string" }, "valeur_energetique_kcal": { "type": "string" }, "dont_acides_gras_satures": { "type": "string" } } }, "denomination_legale_de_vente": { "type": "string" } } }, "attributes": { "type": "array", "items": { "type": "string" } }, "reviews_count": { "type": "integer" }, "reviews_details": { "type": "object", "properties": { "average_rating": { "type": "number" }, "rating_distribution": { "type": "object", "properties": { "1": { "type": "integer" }, "2": { "type": "integer" }, "3": { "type": "integer" }, "4": { "type": "integer" }, "5": { "type": "integer" } } } } } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # Auchan Search **GET** `https://api.piloterr.com/v2/auchan/search` Extract Auchan product listings from keyword searches for insightful market analysis and competitive edge. **Credit cost:** 2 credits per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | Search keyword or Auchan search URL to retrieve product listings. **Accepted formats:** - `pomme`: Plain keyword search - `https://www.auchan.fr/recherche?text=pomme`: Full Auchan search URL **Example:** pomme **Notes:** - **Both keyword and full URL formats are supported.** Use the URL format to reproduce a specific Auchan search with applied filters. - Results include product titles, ratings, review counts, attributes, and images. | | `page` | query | `number` | No | Page number for paginated search results. **Note:** Use the `pagination.has_next_page` field in the response to determine whether additional pages are available. | ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "brand": { "nullable": true }, "image": { "nullable": true }, "title": { "type": "string" }, "rating": { "type": "integer" }, "attributes": { "type": "array", "items": { "type": "string" } }, "reviews_count": { "type": "integer" } } } }, "pagination": { "type": "object", "properties": { "next": { "type": "integer" }, "current": { "type": "integer" }, "other_pages": { "type": "array", "items": { "type": "integer" } }, "has_next_page": { "type": "boolean" } } } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # Auto Top-Up Never run out of credits mid-workflow. Auto Top-Up monitors your credit balance and purchases a credit pack on your behalf the moment your balance drops below a configurable threshold. How it works [#how-it-works] Set a threshold [#set-a-threshold] Choose the percentage of your remaining credits at which the automatic purchase should trigger. When your balance falls below this level, Auto Top-Up activates. Pick a credit pack [#pick-a-credit-pack] Select the one-time credit pack to purchase automatically. The pack is charged to the payment method on file in your account. Credits are added instantly [#credits-are-added-instantly] Once the purchase completes, the credits are added to your balance immediately. No downtime, no failed requests. Enabling Auto Top-Up [#enabling-auto-top-up] 1. Go to **[Settings → Subscription](https://app.piloterr.com)** in your dashboard. 2. Open the **Auto Top-Up** section. 3. Toggle **Enable** and choose a credit pack and a threshold percentage. 4. Click **Save** to activate. Auto Top-Up is only available on paid plans. Users on the Free plan cannot enable automatic purchases. Configuration options [#configuration-options] | Option | Description | | ----------------- | ------------------------------------------------------------------------------------------------------ | | **Credit pack** | The one-time credit bundle purchased automatically when the threshold is reached. | | **Threshold (%)** | The percentage of your remaining credits that triggers the top-up. Accepts values between 10% and 30%. | Billing [#billing] Automatic purchases are charged to the payment method associated with your account. You will receive an invoice by email for each automatic purchase, just like a manual credit purchase. Make sure your payment method is up to date. If a charge fails, Auto Top-Up is automatically **disabled** on your account to prevent repeated failed attempts. You will need to re-enable it manually once your payment method is updated. Built-in protections [#built-in-protections] Auto Top-Up includes two safeguards to prevent unexpected charges: | Protection | How it works | | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Threshold-only trigger** | A purchase only fires when your remaining balance drops below the configured percentage. It never runs on a fixed schedule or at a specific time. | | **72-hour cooldown** | After a top-up completes, the system waits at least 72 hours before it can trigger again, even if your balance drops below the threshold a second time during that window. | | **Auto-disable on failure** | If the Stripe charge fails, Auto Top-Up is automatically disabled to protect your account from repeated failed payment attempts. | Frequently asked questions [#frequently-asked-questions] Will I be charged immediately when I enable Auto Top-Up? [#will-i-be-charged-immediately-when-i-enable-auto-top-up] No. Enabling Auto Top-Up does not trigger a purchase. The charge only fires when your balance actually drops below the configured threshold. Can I be charged multiple times in a short period? [#can-i-be-charged-multiple-times-in-a-short-period] No. A built-in 72-hour cooldown prevents more than one automatic purchase from firing within any 72-hour window, regardless of how your balance fluctuates. Can I disable Auto Top-Up at any time? [#can-i-disable-auto-top-up-at-any-time] Yes. Toggle the **Enable** switch off in **Settings → Subscription → Auto Top-Up** and save. No further automatic purchases will occur. What happens if my payment fails? [#what-happens-if-my-payment-fails] Auto Top-Up is automatically disabled on your account. You will need to update your payment method and re-enable the feature manually from your subscription settings. Is Auto Top-Up available on the Free plan? [#is-auto-top-up-available-on-the-free-plan] No. You need an active paid subscription to enable automatic credit top-ups. # Autodoc Product Related **GET** `https://api.piloterr.com/v2/autodoc/product/related` Vehicle fitment lines per maker for an Autodoc product: models, TecDoc-style ids, and dates from the related-auto flow. **Credit cost:** 2 credits per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | Same **HTTPS product page URL** as the Product endpoint (`query` there = `query` here). Must use a supported Autodoc shop host (see Product / Search documentation for the allowlist). **Example:** `https://www.autodoc.de/ridex/8098144` | | `maker_id` | query | `number` | Yes | TecDoc maker id from `compatibility.cars[]` / `compatibility.trucks[]` (HTML `data-maker-id`), e.g. 121 for VW. | | `vehicle_type` | query | `string` | No | `pkw` (passenger cars) or `lkw` (commercial). Must match the compatibility row. | | `maker_name` | query | `string` | No | Maker label (e.g. VW). Improves parsing of vehicle lines; optional. | | `product_id` | query | `number` | No | Article id if it cannot be inferred from the product URL path. | ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "product_url": { "type": "string" }, "product_id": { "type": "integer" }, "maker_id": { "type": "integer" }, "vehicle_type": { "type": "string" }, "models": { "type": "array", "items": { "type": "string" } }, "vehicles": { "type": "array", "items": { "type": "object", "properties": { "raw": { "type": "string" }, "brand": { "type": "string" }, "model": { "type": "string" }, "end_date": { "type": "string" }, "model_id": { "type": "integer" }, "start_date": { "type": "string" } } } } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # Autodoc Product **GET** `https://api.piloterr.com/v2/autodoc/product` Scrape Autodoc product pages: price, specs, EAN, images, compatibility, and TecDoc-related vehicle data via the Related endpoint. **Credit cost:** 2 credits per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | HTTPS URL of an Autodoc **product** page (detail page with article id in the path). **Example:** https://www.auto-doc.fr/ridex/7999541 The host must be a supported Autodoc shop (same allowlist as Search `domain`; e.g. `www.autodoc.de`, `www.auto-doc.fr`). Other hosts return **400**. **Response includes** (when present on the page): `product_url`, `compatibility` (makers + `fetch` for Related), `specifications`, `oem_numbers`, `seo_summary`. | ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "ean": { "type": "string" }, "name": { "type": "string" }, "price": { "type": "number" }, "images": { "type": "array", "items": { "type": "string" } }, "rating": { "type": "integer" }, "seller": { "type": "string" }, "brand_no": { "type": "integer" }, "currency": { "type": "string" }, "features": { "type": "array", "items": { "type": "string" } }, "subtitle": { "type": "string" }, "reference": { "type": "string" }, "seller_id": { "type": "integer" }, "generic_id": { "type": "integer" }, "product_id": { "type": "integer" }, "breadcrumbs": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "name": { "type": "string" } } } }, "oem_numbers": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "label": { "type": "string" } } } }, "product_url": { "type": "string" }, "seo_summary": { "type": "object", "properties": { "moteurs": { "type": "string" }, "modeles_de_voitures": { "type": "string" }, "annees_de_fabrication": { "type": "string" }, "numero(s)_de_piece_oe": { "type": "string" }, "puissance_(kilowatts)": { "type": "string" }, "numero_d_article_du_fabricant": { "type": "string" }, "puissance_du_moteur_(chevaux)": { "type": "string" } } }, "availability": { "type": "string" }, "generic_name": { "type": "string" }, "goods_ending": { "type": "integer" }, "compatibility": { "type": "object", "properties": { "cars": { "type": "array", "items": { "type": "object", "properties": { "fetch": { "type": "object", "properties": { "path": { "type": "string" }, "params": { "type": "object", "properties": { "query": { "type": "string" }, "maker_id": { "type": "integer" }, "maker_name": { "type": "string" }, "product_id": { "type": "integer" }, "vehicle_type": { "type": "string" } } } } }, "maker": { "type": "string" }, "maker_id": { "type": "integer" }, "vehicle_type": { "type": "string" } } } }, "trucks": { "type": "array", "items": {} } } }, "has_360_photo": { "type": "boolean" }, "reviews_count": { "type": "integer" }, "specifications": { "type": "object", "properties": { "etat": { "type": "string" }, "hauteur": { "type": "string" }, "perfore": { "type": "string" }, "surface": { "type": "string" }, "diametre": { "type": "string" }, "materiel": { "type": "string" }, "fabricant": { "type": "string" }, "traitement": { "type": "string" }, "numero_de_ean": { "type": "string" }, "nombre_de_trous": { "type": "string" }, "numero_d_article": { "type": "string" }, "annee_a_partir_de": { "type": "string" }, "cote_d_assemblage": { "type": "string" }, "cercle_de_percage_ø": { "type": "string" }, "diametre_du_centrage": { "type": "string" }, "type_de_disque_de_frein": { "type": "string" }, "epaisseur_du_disque_de_frein": { "type": "string" }, "diametre_d_alesage_du_boulon_de_roue": { "type": "string" }, "article_complementaire_info_complementaire_2": { "type": "string" } } }, "rating_percentage": { "type": "integer" }, "discount_percentage": { "type": "integer" } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # Autodoc Search **GET** `https://api.piloterr.com/v2/autodoc/search` Search Autodoc by URL: keyword pages use `/search?keyword=…` (e.g. auto-doc.fr, autodoc.de). Extract product cards, prices, and pagination. **Credit cost:** 2 credits per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | Full Autodoc **search or listing** URL, or **path only** when `domain` sets the shop. **Typical keyword search (full URL, `domain` ignored):** ``` https://www.auto-doc.fr/search?keyword=ffe https://www.autodoc.de/search?keyword=dz ``` **Path + `domain` (equivalent to the URLs above):** - `query`: `search?keyword=ffe` - `domain`: `auto-doc.fr` → `https://www.auto-doc.fr/search?keyword=ffe` Other listing-style paths still exist on some shops (e.g. `listing?string=…`); pass whatever path the site uses. **Rules:** - If `query` starts with `http://` or `https://`, `domain` is ignored. - If `query` has no host, `domain` must be **exactly** one hostname from the allowed shop list below (no `www.`, no `https://`). Wrong host → **400**. - Omit `domain` to default to `autodoc.de`. - France uses **`auto-doc.fr`**. The domain **`autodoc.fr` does not exist.** **Allowed shop hostnames for `domain`:** - `autodoc.de` - `auto-doc.ch` - `autodoc24.ch` - `auto-doc.at` - `autodoc.lu` - `autodoc.bg` - `autodoc.be` - `auto-doc.be` - `autodoc.cz` - `autodoc.dk` - `autodoc.ee` - `autodoc.es` - `autodoc.fi` - `auto-doc.fr` - `autodoc24.fr` - `autodoc.co.uk` - `autodoc.gr` - `autodoc.hu` - `auto-doc.ie` - `auto-doc.it` - `autodoc24.it` - `autodoc.lt` - `autodoc.lv` - `autodoc.nl` - `autodoc24.nl` - `autodoc.co.no` - `autodoc.pl` - `auto-doc.pt` - `autodoc24.ro` - `autodoc.se` - `autodoc.si` - `autodoc.sk` - `autodoc.parts` | | `domain` | query | `string` | No | Regional shop hostname **without** `https://` or `www.` (e.g. `auto-doc.fr`, `autodoc.de`, `autodoc.pl`). France: **`auto-doc.fr`** only (`autodoc.fr` is not a valid host). Only values from the allowlist in the `query` parameter description work. Omit to use `autodoc.de`. | ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "price": { "type": "number" }, "seller": { "type": "string" }, "brand_no": { "type": "string" }, "discount": { "type": "integer" }, "360_photo": { "nullable": true }, "reference": { "type": "string" }, "seller_id": { "type": "integer" }, "product_id": { "type": "string" }, "product_url": { "type": "string" }, "availability": { "type": "string" }, "generic_name": { "type": "string" }, "product_image": { "type": "string" }, "reviews_count": { "type": "integer" }, "original_price": { "type": "number" } } } }, "pagination": { "type": "object", "properties": { "next": { "type": "integer" }, "current": { "type": "integer" }, "other_pages": { "type": "array", "items": { "type": "integer" } }, "has_next_page": { "type": "boolean" } } } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # AutoScout24 Ad **GET** `https://api.piloterr.com/v2/autoscout24/ad` Extract full details from an AutoScout24 car listing, including price, vehicle specifications, seller info, and equipment. **Credit cost:** 1 credit per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | Full AutoScout24 car listing URL from any supported domain. **Supported domains:** `.de`, `.be`, `.es`, `.fr`, `.it`, `.lu`, `.nl`, `.at`, `.bg`, `.cz`, `.com`, `.hr`, `.pl`, `.ro`, `.ru`, `.se`, `.com.tr`, `.com.ua`, `.hu` **Example:** https://www.autoscout24.fr/offres/peugeot-208-puretech-82ch-s-s-bvm5-allure-1-ere-main-distribut-essence-blanc-51a0c24c-84e6-4ed8-af6b-1b8ef193ae84 **Note:** The UUID at the end of the URL identifies the specific listing. Expired ads will return an error. | ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "id": { "type": "string" }, "image": { "type": "string" }, "price": { "type": "object", "properties": { "price_formatted": { "type": "string" }, "price_evaluation": { "type": "integer" } } }, "images": { "type": "array", "items": { "type": "string" } }, "prices": { "type": "object", "properties": { "dealer": { "type": "object", "properties": { "price": { "type": "string" }, "category": { "type": "integer" }, "price_raw": { "type": "integer" }, "negotiable": { "type": "boolean" }, "evaluation_ranges": { "type": "array", "items": { "type": "object", "properties": { "maximum": { "type": "integer" }, "minimum": { "nullable": true }, "category": { "type": "integer" } } } } } } } }, "seller": { "type": "object", "properties": { "type": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" }, "location": { "type": "object", "properties": { "city": { "type": "string" }, "country": { "type": "string" }, "zip": { "type": "string" } } } } }, "vehicle": { "type": "object", "properties": { "make": { "type": "string" }, "model": { "type": "string" }, "fuel": { "type": "string" }, "transmission": { "type": "string" }, "mileage": { "type": "integer" }, "year": { "type": "integer" }, "engine_displacement": { "type": "string" }, "power_kw": { "type": "integer" }, "color": { "type": "string" } } }, "description": { "type": "string" }, "equipment": { "type": "array", "items": { "type": "string" } } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # AutoScout24 Search **GET** `https://api.piloterr.com/v2/autoscout24/search` Search for car listings on AutoScout24 by URL, returning paginated results with vehicle details, pricing, and seller info. **Credit cost:** 1 credit per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | Full AutoScout24 search URL from any supported domain. Filter parameters, make/model, and pagination in the URL are all respected. **Supported domains:** `.de`, `.be`, `.es`, `.fr`, `.it`, `.lu`, `.nl`, `.at`, `.bg`, `.cz`, `.com`, `.hr`, `.pl`, `.ro`, `.ru`, `.se`, `.com.tr`, `.com.ua`, `.hu` **Example:** https://www.autoscout24.fr/lst/volkswagen/golf?atype=C **Notes:** - Pagination is embedded in the URL (e.g. append `&page=2` for the next page) - Filters like fuel type, price range, mileage, and year can be included in the URL | ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "ad_tier": { "type": "string" }, "vehicle": { "type": "object", "properties": { "fuel": { "type": "string" }, "make": { "type": "string" }, "type": { "type": "string" }, "model": { "type": "string" }, "variant": { "type": "string" }, "transmission": { "type": "string" }, "mileage_in_km": { "type": "string" }, "model_version_input": { "type": "string" }, "engine_displacement_in_c_c_m": { "type": "string" } } }, "seller": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "company_name": { "type": "string" }, "contact_name": { "type": "string" }, "phones": { "type": "array", "items": { "type": "object", "properties": { "call_to": { "type": "string" }, "phone_type": { "type": "string" } } } } } }, "location": { "type": "object", "properties": { "zip": { "type": "string" }, "city": { "type": "string" }, "country_code": { "type": "string" } } }, "tracking": { "type": "object", "properties": { "price": { "type": "string" }, "mileage": { "type": "string" }, "fuel_type": { "type": "string" }, "price_label": { "type": "string" }, "first_registration": { "type": "string" } } }, "vehicle_details": { "type": "object", "properties": { "gearbox": { "type": "string" }, "calendar": { "type": "string" }, "speedometer": { "type": "string" }, "mileage_odometer": { "type": "string" } } }, "available_now": { "type": "boolean" }, "images": { "type": "array", "items": { "type": "string" } } } } }, "pagination": { "type": "object", "properties": { "next": { "type": "integer" }, "current": { "type": "integer" }, "total_pages": { "type": "integer" }, "has_next_page": { "type": "boolean" }, "total_results": { "type": "integer" } } } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # Best Practices Follow these guidelines to build integrations that are reliable, cost-efficient, and easy to maintain. Credit efficiency [#credit-efficiency] Check your balance before large batches [#check-your-balance-before-large-batches] Before triggering a high-volume operation, verify you have enough credits. The [Usage](/usage) endpoint is free and returns your current balance in real time. ```bash curl "https://api.piloterr.com/v2/usage" \ -H "x-api-key: YOUR_API_KEY" ``` Enable [Auto Top-Up](/auto-top-up) to automatically refill your balance when it drops below a threshold, so your workflows keep running without interruption. Avoid redundant calls [#avoid-redundant-calls] Cache results on your side whenever the underlying data is unlikely to change between requests. Re-fetching identical inputs wastes credits. ```typescript const cache = new Map() async function fetchCached(key: string, fetcher: () => Promise) { if (cache.has(key)) return cache.get(key) const result = await fetcher() cache.set(key, result) return result } ``` Only call what you need [#only-call-what-you-need] Each endpoint has a defined credit cost listed on the [Credits](/credits) page. Prefer lighter endpoints when a full response is not required. *** Authentication [#authentication] Store keys in environment variables [#store-keys-in-environment-variables] Never hardcode your API key in source code. Use environment variables and load them at runtime. ```typescript const apiKey = process.env.PILOTERR_API_KEY if (!apiKey) throw new Error("API key is not set") ``` ```python import os api_key = os.environ["PILOTERR_API_KEY"] ``` ```php $apiKey = getenv('PILOTERR_API_KEY'); ``` ```go apiKey := os.Getenv("PILOTERR_API_KEY") ``` Use separate keys per environment [#use-separate-keys-per-environment] Create distinct API keys for development, staging, and production in your [dashboard](https://app.piloterr.com). This lets you revoke or rotate a compromised key without affecting other environments. | Environment | Recommended category | | ------------ | -------------------- | | Local dev | `development` | | CI / staging | `development` | | Production | `production` | Rotate keys periodically [#rotate-keys-periodically] Treat API keys like passwords. Set an expiry date on sensitive keys and rotate them on a regular schedule from the API Keys section of your account settings. Never expose your API key in client-side code, browser requests, or public repositories. Always proxy calls through your own backend. *** Error handling [#error-handling] Always check the HTTP status code [#always-check-the-http-status-code] Do not assume a request succeeded. Every response should be checked against its HTTP status code before processing the body. See the [Error Handling](/error-handling) guide for a full breakdown. Retry on transient errors [#retry-on-transient-errors] Server errors (`500`) and network timeouts are transient. Implement exponential backoff to retry automatically: ```typescript async function fetchWithRetry(url: string, options: RequestInit, maxRetries = 3) { for (let attempt = 0; attempt <= maxRetries; attempt++) { try { const res = await fetch(url, options) if (res.status === 500 && attempt < maxRetries) { await new Promise(r => setTimeout(r, 500 * 2 ** attempt)) continue } return res } catch { if (attempt === maxRetries) throw new Error("Max retries reached") await new Promise(r => setTimeout(r, 500 * 2 ** attempt)) } } } ``` Never retry on 402 without topping up [#never-retry-on-402-without-topping-up] A `402 Payment Required` response means your balance is empty. Retrying the same call immediately will not help. Add credits from your [dashboard](https://app.piloterr.com) or enable [Auto Top-Up](/auto-top-up). *** Rate limits [#rate-limits] Spread requests over time [#spread-requests-over-time] If you need to send a large number of calls, distribute them across time rather than firing them all at once. A simple delay between iterations prevents hitting rate limits. ```typescript const DELAY_MS = 100 // adjust based on your plan for (const item of items) { await processItem(item) await new Promise(r => setTimeout(r, DELAY_MS)) } ``` Monitor the 401 Rate Limit Exceeded response [#monitor-the-401-rate-limit-exceeded-response] When rate-limited, the API returns `401` with status `Rate Limit Exceeded`. Back off and wait before retrying. Consider upgrading your plan if you consistently hit limits. *** Security [#security] Never make API calls from the browser [#never-make-api-calls-from-the-browser] Your API key would be visible to anyone who inspects the network tab. Always route calls through your own server. ``` Browser → Your backend → Piloterr API ``` Validate and sanitize inputs [#validate-and-sanitize-inputs] If your application accepts user-supplied parameters that are passed to the API (URLs, search queries, etc.), sanitize them to prevent injection or unexpected behavior. *** Monitoring [#monitoring] Track credit consumption [#track-credit-consumption] Query the [Usage](/usage) endpoint on a schedule (e.g. daily) and alert when consumption exceeds a threshold. This prevents surprises at the end of a billing period. | Metric | Why it matters | | --------------------------- | -------------------------------- | | `remaining` | Warns you before credits run out | | `subscription.percent_used` | Tracks your plan utilization | | `credits.remaining` | Monitors extra credit balance | Log request context [#log-request-context] Store the HTTP status code and a timestamp for every API call. This makes it easy to audit credit consumption and debug failures after the fact. ```typescript async function apiCall(endpoint: string, params: Record) { const url = new URL(`https://api.piloterr.com${endpoint}`) Object.entries(params).forEach(([k, v]) => url.searchParams.set(k, v)) const res = await fetch(url.toString(), { headers: { "x-api-key": process.env.API_KEY! }, }) console.log(JSON.stringify({ endpoint, status: res.status, billed: res.status === 200 || res.status === 201, timestamp: new Date().toISOString(), })) return res } ``` *** Checklist [#checklist] Use this checklist before going to production: * [ ] API key stored in an environment variable, not in source code * [ ] Separate keys for development and production * [ ] HTTP status codes checked on every response * [ ] Retry logic with exponential backoff for `500` errors * [ ] No retries on `402` without adding credits first * [ ] Rate limit handling in place * [ ] Credit balance monitored and alerts configured * [ ] Auto Top-Up enabled (or a manual top-up process defined) * [ ] All API calls proxied through your backend *** See also: [Error Handling](/error-handling) for a complete list of status codes and [Glossary](/glossary) for term definitions. # Bestbuy Product **GET** `https://api.piloterr.com/v2/bestbuy/product` Extract full product details from a Best Buy product page, including pricing, specifications, customer reviews, and availability. **Credit cost:** 1 credit per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | Full Best Buy product page URL. **Example:** https://www.bestbuy.com/site/macbook-air-13-6-laptop-apple-m2-chip-8gb-memory-256gb-ssd-midnight/6509650.p **Notes:** - The URL must point to a product detail page ending with `.p` or `.p?skuId={id}` - Pass the product URL exactly as displayed in your browser | ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "pricing": { "type": "object", "properties": { "sku_id": { "type": "string" }, "pdp_url": { "type": "string" }, "customer_price": { "type": "integer" }, "gsp_unit_price": { "type": "integer" } } }, "reviews": { "type": "object", "properties": { "rating": { "type": "number" }, "rating_count": { "type": "integer" }, "headline": { "type": "string" } } }, "categories": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } } }, "specifications": { "type": "object", "properties": { "brand": { "type": "string" }, "model": { "type": "string" }, "screen_size": { "type": "string" }, "processor": { "type": "string" }, "ram": { "type": "string" }, "storage": { "type": "string" }, "color": { "type": "string" }, "operating_system": { "type": "string" }, "battery_life": { "type": "string" } } } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # Bestbuy Search **GET** `https://api.piloterr.com/v2/bestbuy/search` Search for products on Best Buy by keyword, returning results with prices, ratings, images, and discount information. **Credit cost:** 1 credit per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | Search keyword to find products on Best Buy. **Example:** macbook **Note:** Use short, targeted keywords for best results. Category names, brand names, or product types all work well. | | `page` | query | `number` | No | Page number for pagination. **Example:** Pass `2` to retrieve the second page of results. | | `sort` | query | `string` | No | Sort order for search results. - `best_selling`: Sort by best-selling products (default) - `best_discount`: Sort by highest discount percentage | ## Responses ### 200 Successful response ```json { "type": "array", "items": { "type": "object", "properties": { "sku": { "type": "string" }, "url": { "type": "string" }, "name": { "type": "string" }, "save": { "type": "string" }, "image": { "type": "string" }, "model": { "type": "string" }, "price": { "type": "integer" }, "rating": { "type": "number" }, "is_sold_out": { "type": "boolean" }, "rating_count": { "type": "integer" }, "original_price": { "type": "integer" } } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # Bing Search **GET** `https://api.piloterr.com/v2/bing/search` Scrape real-time Bing search results with full control over location, language, and pagination. **Credit cost:** 1 credit per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | The search query to execute on Bing. Supports all Bing advanced search operators. **Examples:** - `artificial intelligence` — standard keyword search - `site:github.com python scraper` — restrict results to a specific domain - `intitle:"machine learning"` — match the page title - `inurl:blog python` — match part of the URL **Example:** artificial intelligence news 2024 | | `page` | query | `number` | No | Page number of results to retrieve. Used for pagination. - `1`: First page (default) - `2`: Second page - `3`: Third page, etc. | | `num` | query | `number` | No | Number of results per page. **Minimum:** `10`, **Maximum:** `50`. **Note:** This parameter is only a suggestion and might not reflect the actual number of results returned. | | `location` | query | `string` | No | City or region from which the search should originate. If multiple locations match, the most popular one is selected. **Note:** Cannot be used together with `lat`/`lon`. It is recommended to specify location at the city level. **Example:** Austin | | `lat` | query | `number` | No | GPS latitude coordinate for the search origin. **Example:** 48.8566 | | `lon` | query | `number` | No | GPS longitude coordinate for the search origin. **Example:** 2.3522 | | `mkt` | query | `string` | No | Market code combining language and country, in the form `-`. Defines where the results come from. - `en-US`: English, United States (default) - `fr-FR`: French, France - `de-DE`: German, Germany - `es-ES`: Spanish, Spain **Note:** Cannot be used together with `cc`. | | `cc` | query | `string` | No | Two-letter ISO 3166-1 country code defining the country to search from. - `us`: United States - `de`: Germany - `gb`: United Kingdom - `fr`: France **Note:** Cannot be used together with `mkt`. | ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "next": { "nullable": true }, "current": { "type": "integer" }, "other_pages": { "type": "array", "items": {} }, "has_next_page": { "type": "boolean" } } }, "organic_results": { "type": "array", "items": { "type": "object", "properties": { "link": { "type": "string" }, "title": { "type": "string" }, "domain": { "type": "string" }, "snippet": { "nullable": true }, "position": { "type": "integer" }, "displayed_link": { "type": "string" }, "snippet_matched": { "type": "array", "items": {} } } } }, "search_parameters": { "type": "object", "properties": { "q": { "type": "string" }, "cc": { "nullable": true }, "lat": { "nullable": true }, "lon": { "nullable": true }, "mkt": { "nullable": true }, "num": { "nullable": true }, "page": { "type": "integer" }, "engine": { "type": "string" }, "location": { "nullable": true }, "bing_domain": { "type": "string" } } }, "search_information": { "type": "object", "properties": { "total_results": { "nullable": true } } } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # Brave Search **GET** `https://api.piloterr.com/v2/brave/search` Access the Brave search engine results directly through our efficient Piloterr service for reliable data scraping. **Credit cost:** 1 credit per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | The search query to execute on Brave Search. Supports all standard Brave search operators. **Examples:** - `machine learning` — standard keyword search - `site:github.com scraper` — restrict results to a specific domain - `intitle:"growth hacking"` — match the page title - `inurl:blog python` — match part of the URL **Example:** best programming languages 2024 | | `page` | query | `number` | No | Page number of results to retrieve. Used for pagination. - `1`: First page (default) - `2`: Second page - `3`: Third page, etc. | ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "organic_results": { "type": "array", "items": { "type": "object", "properties": { "link": { "type": "string" }, "title": { "type": "string" }, "domain": { "type": "string" }, "snippet": { "type": "string" }, "position": { "type": "integer" }, "displayed_link": { "type": "string" }, "snippet_matched": { "type": "array", "items": {} } } } }, "search_parameters": { "type": "object", "properties": { "q": { "type": "string" }, "page": { "type": "integer" }, "engine": { "type": "string" } } } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # Carrefour Product **GET** `https://api.piloterr.com/v2/carrefour/product` Extract full product details from a Carrefour product page, including price, brand, nutritional info, packaging, and availability. **Credit cost:** 2 credits per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | Full Carrefour product page URL from `carrefour.fr`. **Example:** https://www.carrefour.fr/p/oeufs-de-caille-le-gaulois-3266980075934 **Notes:** - **Only `carrefour.fr` is currently supported.** Other domains (e.g. `carrefour.es`, `carrefour.it`) are not supported. - The URL must point to a product detail page (starting with `/p/`). | ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "brand": { "type": "string" }, "image": { "type": "string" }, "price": { "type": "string" }, "title": { "type": "string" }, "currency": { "type": "string" }, "packaging": { "type": "string" }, "nutriscore": { "nullable": true }, "price_float": { "type": "number" }, "price_per_unit": { "type": "string" }, "price_per_unit_float": { "type": "number" }, "price_per_unit_measure": { "type": "string" }, "price_per_unit_currency": { "type": "string" }, "short_title": { "type": "string" }, "business_type": { "type": "string" }, "is_best_seller": { "type": "boolean" }, "customer_reviews": { "type": "object", "properties": { "count": { "type": "integer" }, "rates": { "nullable": true }, "average": { "type": "integer" } } }, "categories": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "slug": { "type": "string" }, "label": { "type": "string" }, "level": { "type": "integer" } } } }, "more_offers": { "type": "object", "properties": { "count": { "type": "integer" }, "best_offer_id": { "nullable": true }, "best_offer_price": { "nullable": true } } } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # Carrefour Search **GET** `https://api.piloterr.com/v2/carrefour/search` Search for products on Carrefour by keyword or URL, returning structured listings with prices, ratings, and pagination. **Credit cost:** 2 credits per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | Search keyword or full Carrefour search page URL. **Accepted formats:** - `pomme` — keyword search - `https://www.carrefour.fr/s?q=pomme` — full search URL **Example:** pomme **Note:** Only `carrefour.fr` is currently supported. | | `domain` | query | `string` | No | Carrefour domain to search on. - `fr`: carrefour.fr (default, only supported domain) **Note:** Only the `fr` domain is currently supported. | | `page` | query | `number` | No | Page number to retrieve. **Example:** Pass `2` to retrieve the second page of results. | ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "slug": { "type": "string" }, "image": { "type": "string" }, "price": { "type": "string" }, "title": { "type": "string" }, "rating": { "type": "number" }, "currency": { "type": "string" }, "sponsored": { "type": "boolean" }, "price_float": { "type": "number" }, "reviews_count": { "type": "integer" } } } }, "pagination": { "type": "object", "properties": { "next": { "type": "integer" }, "current": { "type": "integer" }, "has_next_page": { "type": "boolean" } } } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # Carrefour Suggest **GET** `https://api.piloterr.com/v2/carrefour/suggest` Get product suggestions from Carrefour by keyword or EAN, returning matching products with pricing, availability, and product details. **Credit cost:** 1 credit per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | Search keyword or EAN code to get product suggestions from Carrefour. **Accepted formats:** - `coca` — keyword (e.g. brand name, product type) - `3276550063551` — EAN barcode **Example (keyword):** coca **Example (EAN):** 3276550063551 **Note:** Only `carrefour.fr` is currently supported. | ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "links": { "type": "object", "properties": { "self": { "type": "string" }, "reviews": { "type": "string" } } }, "attributes": { "type": "object", "properties": { "ean": { "type": "string" }, "slug": { "type": "string" }, "brand": { "type": "string" }, "title": { "type": "string" }, "format": { "type": "string" }, "packaging": { "type": "string" }, "nutriscore": { "nullable": true }, "businesstype": { "type": "string" }, "shorttitle": { "type": "string" }, "customerreviews": { "type": "object", "properties": { "count": { "type": "integer" }, "rates": { "nullable": true }, "average": { "type": "number" } } }, "categories": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "slug": { "type": "string" }, "label": { "type": "string" }, "level": { "type": "integer" } } } }, "offers": { "type": "object", "properties": { "5000112611861": { "type": "object", "properties": { "0261_150_6": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "attributes": { "type": "object", "properties": { "ean": { "type": "string" }, "price": { "type": "object", "properties": { "price": { "type": "number" }, "perunit": { "type": "number" }, "perunitlabel": { "type": "string" }, "unitofmeasure": { "type": "string" } } }, "availability": { "type": "object", "properties": { "purchasable": { "type": "boolean" } } } } } } } } } } } } } } } } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # Cdiscount Product Offer **GET** `https://api.piloterr.com/v2/cdiscount/product/offer` Retrieve all marketplace seller offers for a Cdiscount product, including prices, seller ratings, shipping costs, and availability. **Credit cost:** 2 credits per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | Cdiscount product offer page URL. Pass the `multiple_offer_url` value returned by the Cdiscount Product API. **Example:** https://www.cdiscount.com/mp-352880-auc3283981039048.html **How to get this URL:** - Call the Cdiscount Product API with any product URL. - Extract the `multiple_offer_url` field from the response. - Use that URL as the `query` parameter here. **Note:** Only URLs with the pattern `/mp-{id}-{ean}.html` are accepted. Regular product page URLs will not work. | ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "price": { "type": "number" }, "seller": { "type": "object", "properties": { "url": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "rating": { "type": "object", "properties": { "rating": { "type": "number" }, "reviews_count": { "type": "integer" }, "score_percentage": { "type": "integer" } } }, "sales_count": { "type": "integer" } } }, "condition": { "type": "string" }, "shipped_by": { "type": "string" }, "availability": { "type": "string" }, "delivery_time": { "type": "string" }, "shipping_cost": { "type": "string" }, "shipping_country": { "type": "string" } } } } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # Cdiscount Product **GET** `https://api.piloterr.com/v2/cdiscount/product` Extract full product details from a Cdiscount product page, including price, seller, ratings, specifications, and offers. **Status:** Degraded **Credit cost:** 2 credits per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | Full Cdiscount product page URL. **Example:** https://www.cdiscount.com/informatique/ordinateurs-pc-portables/acemagic-pc-portables-gaming/f-1070992-aaaph06865.html **Notes:** - Only standard Cdiscount product URLs are accepted (e.g. `/f-{category}-{id}.html`). - Offer comparison pages (`/mp-{id}-{ean}.html`) should be used with the Cdiscount Product Offer endpoint instead. | ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "id": { "type": "string" }, "ean": { "type": "string" }, "url": { "type": "string" }, "brand": { "type": "string" }, "price": { "type": "number" }, "title": { "type": "string" }, "images": { "type": "array", "items": { "type": "string" } }, "rating": { "type": "integer" }, "seller": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "rating": { "type": "integer" }, "sales_count": { "type": "integer" }, "reviews_count": { "type": "integer" } } }, "is_cdav": { "type": "boolean" }, "currency": { "type": "string" }, "offer_id": { "type": "integer" }, "condition": { "type": "string" }, "multiple_offer_url": { "type": "string" }, "multiple_offer_text": { "type": "string" }, "multiple_offer_starting_price": { "type": "number" }, "description": { "type": "string" }, "is_available": { "type": "boolean" }, "other_offers": { "type": "object", "properties": { "total_offers": { "type": "integer" }, "lowest_price_new": { "type": "number" }, "new_offers_count": { "type": "integer" }, "lowest_price_used": { "nullable": true }, "used_offers_count": { "type": "integer" } } }, "delivery_info": { "type": "string" }, "reviews_count": { "type": "integer" }, "original_price": { "type": "number" } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # Cdiscount Search **GET** `https://api.piloterr.com/v2/cdiscount/search` Extract product listings from Cdiscount search results or category pages for market intelligence and competitive analysis. **Credit cost:** 2 credits per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | Cdiscount search results page URL. Use any URL from a search or category browse on cdiscount.com. **Example:** https://www.cdiscount.com/search/10/laptop.html **Notes:** - You can use keyword search URLs (e.g. `/search/10/{keyword}.html`) or category browse URLs (e.g. `/informatique/ordinateurs-pc-portables/...`) - Pagination and filter parameters present in the URL are respected. | ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "products": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "image": { "type": "string" }, "price": { "type": "number" }, "title": { "type": "string" }, "rating": { "type": "integer" }, "seller": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" } } }, "description": { "nullable": true }, "is_sponsored": { "type": "boolean" }, "original_price": { "type": "number" }, "free_shipping": { "type": "boolean" }, "reviews_count": { "type": "integer" } } } }, "pagination": { "type": "object", "properties": { "next": { "type": "integer" }, "current": { "type": "integer" }, "other_pages": { "type": "array", "items": { "type": "integer" } }, "total_pages": { "type": "integer" }, "has_next_page": { "type": "boolean" } } } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # Chewy Product **GET** `https://api.piloterr.com/v2/chewy/product` Retrieve full product details from a Chewy product page URL, including pricing, variants, ratings, and availability. **Credit cost:** 2 credits per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | Chewy product page URL to scrape. **Example:** https://www.chewy.com/dp/371150 **Notes:** - The URL must be a valid Chewy product detail page (starts with `https://www.chewy.com/dp/` or a full product slug URL). - Variant-level item IDs (e.g. `/dp/116881`) are supported — the API will return the full product graph including all variants. | ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "ROOT_QUERY": { "type": "object", "properties": { "pdp": { "type": "object", "properties": { "__typename": { "type": "string" }, "featureToggles": { "type": "object", "properties": { "__typename": { "type": "string" }, "qnaEnabled": { "type": "boolean" }, "reviewsEnabled": { "type": "boolean" }, "fbtWidgetEnabled": { "type": "boolean" }, "loyaltyFeaturesEnabled": { "type": "boolean" }, "realTimeDealsEnabled": { "type": "boolean" } } } } }, "__typename": { "type": "string" }, "currentUser": { "nullable": true }, "item({\"id\":\"371150\"})": { "type": "object", "properties": { "__ref": { "type": "string" } } }, "product({\"id\":\"371138\"})": { "type": "object", "properties": { "__ref": { "type": "string" } } } } }, "Item:SXRlbTozNzExNTA=": { "type": "object", "properties": { "id": { "type": "string" }, "gtin": { "type": "string" }, "name": { "type": "string" }, "entryID": { "type": "string" }, "inStock": { "type": "boolean" }, "isFresh": { "type": "boolean" }, "isGiftCard": { "type": "boolean" }, "isLiveFeed": { "type": "boolean" }, "isBundle": { "type": "boolean" }, "isFrozen": { "type": "boolean" }, "mapPrice": { "type": "string" }, "isInStock": { "type": "boolean" }, "isVetDiet": { "type": "boolean" }, "onSpecial": { "type": "boolean" }, "__typename": { "type": "string" }, "dimensions": { "type": "string" }, "isPublished": { "type": "boolean" }, "perUnitPrice": { "type": "string" }, "autoshipPrice": { "type": "string" }, "isUnavailable": { "type": "boolean" }, "isPrescription": { "type": "boolean" }, "advertisedPrice": { "type": "string" }, "description": { "type": "string" }, "keyBenefits": { "type": "array", "items": { "type": "string" } }, "shippingMessage": { "type": "string" }, "autoshipDiscountPct": { "type": "string" }, "unitOfMeasureString": { "type": "string" }, "partNumber": { "type": "string" } } }, "Product:UHJvZHVjdDozNzExMzg=": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "rating": { "type": "number" }, "entryID": { "type": "string" }, "ratingCount": { "type": "integer" }, "manufacturerName": { "type": "string" }, "__typename": { "type": "string" }, "isEnsemble": { "type": "boolean" }, "partNumber": { "type": "string" }, "description": { "type": "string" } } } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # Chewy Search **GET** `https://api.piloterr.com/v2/chewy/search` Scrape Chewy search, brand, or category pages to retrieve a list of products with pricing, ratings, and availability. **Credit cost:** 2 credits per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | Chewy search or browse URL to scrape results from. Supported URL types: - `search`: `https://www.chewy.com/s?query=dog+food` - `brand page`: `https://www.chewy.com/brands/feliway-6614` - `category page`: `https://www.chewy.com/b/dry-food-294` **Example:** https://www.chewy.com/brands/feliway-6614 **Notes:** - The URL must be a valid Chewy listing, search, or brand page. - Pagination is handled internally; the API returns results from the first page of the given URL. | ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "ppu": { "type": "string" }, "href": { "type": "string" }, "name": { "type": "string" }, "image": { "type": "string" }, "is_ad": { "type": "boolean" }, "is_atf": { "type": "boolean" }, "is_new": { "type": "boolean" }, "rating": { "type": "number" }, "is_deal": { "type": "boolean" }, "in_stock": { "type": "boolean" }, "is_fresh": { "type": "boolean" }, "is_bundle": { "type": "boolean" }, "is_frozen": { "type": "boolean" }, "description": { "type": "string" }, "part_number": { "type": "string" }, "manufacturer": { "type": "string" }, "rating_count": { "type": "integer" }, "strike_price": { "type": "string" }, "display_price": { "type": "string" }, "autoship_price": { "type": "string" }, "is_rx_vet_diet": { "type": "boolean" }, "is_prescription": { "type": "boolean" }, "is_discontinued": { "type": "boolean" } } } } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # Company Database **GET** `https://api.piloterr.com/v2/company` Retrieve comprehensive company data including financials, technologies, social profiles, and location by domain name. **Credit cost:** 1 credit per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | The domain name of the company to look up. Accepts multiple formats: - `gucci.com`: bare domain name - `https://gucci.com`: full URL format - `www.gucci.com`: www-prefixed domain **Note:** Using a unique domain name ensures accuracy and avoids ambiguity that may arise from common company names or spelling variations. **Example:** gucci.com | ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "name": { "type": "string" }, "domain": { "type": "string" }, "domain_name": { "type": "string" }, "domain_tld": { "type": "string" }, "business_type": { "nullable": true }, "monthly_visitors": { "type": "string" }, "phone_number": { "type": "string" }, "revenue": { "type": "string" }, "staff_range": { "type": "string" }, "founded": { "type": "integer" }, "updated_at": { "nullable": true }, "description": { "type": "string" }, "industries": { "type": "array", "items": { "type": "string" } }, "social_networks": { "type": "object", "properties": { "facebook": { "type": "string" }, "instagram": { "type": "string" }, "linkedin": { "type": "string" }, "pinterest": { "type": "string" }, "twitter": { "type": "string" }, "youtube": { "type": "string" }, "linkedin_sales_navigator": { "type": "string" }, "instagram_id": { "type": "string" }, "facebook_id": { "type": "string" }, "twitter_id": { "type": "string" }, "youtube_id": { "type": "string" }, "pinterest_id": { "type": "string" }, "linkedin_id_alpha": { "type": "string" }, "linkedin_id_numeric": { "type": "integer" } } }, "technologies": { "type": "array", "items": { "type": "string" } }, "technology_categories": { "type": "array", "items": { "type": "string" } }, "location": { "type": "object", "properties": { "address": { "nullable": true }, "city": { "type": "string" }, "lat": { "type": "string" }, "lng": { "type": "string" }, "postcode": { "type": "string" }, "country": { "type": "string" }, "country_code": { "type": "string" } } } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # Credits Each API call consumes credits from your account balance. The table below lists every endpoint and its cost. You are charged for successful requests: `200` for synchronous calls and `201` for async jobs. `404` billing is endpoint-specific (check each endpoint page). All other responses (4xx, 5xx) are free. | Endpoint | Method | Path | Credits | | --------------------------------------------------------------- | ------ | ----------------------------------- | ------- | | [Allegro Product](/allegro-product) | `GET` | `/v2/allegro/product` | 2 | | [Allegro Search](/allegro-search) | `GET` | `/v2/allegro/search` | 2 | | [Amazon Product](/amazon-product) | `GET` | `/v2/amazon/product` | 1 | | [Amazon Product Offer](/amazon-product-offer) | `GET` | `/v2/amazon/product/offer` | 1 | | [Amazon Search](/amazon-search) | `GET` | `/v2/amazon/search` | 1 | | [Auchan Product](/auchan-product) | `GET` | `/v2/auchan/product` | 2 | | [Auchan Search](/auchan-search) | `GET` | `/v2/auchan/search` | 2 | | [Autodoc Product](/autodoc-product) | `GET` | `/v2/autodoc/product` | 2 | | [Autodoc Product Related](/autodoc-product-related) | `GET` | `/v2/autodoc/product/related` | 2 | | [Autodoc Search](/autodoc-search) | `GET` | `/v2/autodoc/search` | 2 | | [AutoScout24 Ad](/autoscout24-ad) | `GET` | `/v2/autoscout24/ad` | 1 | | [AutoScout24 Search](/autoscout24-search) | `GET` | `/v2/autoscout24/search` | 1 | | [Bestbuy Product](/bestbuy-product) | `GET` | `/v2/bestbuy/product` | 1 | | [Bestbuy Search](/bestbuy-search) | `GET` | `/v2/bestbuy/search` | 1 | | [Bing Search](/bing-search) | `GET` | `/v2/bing/search` | 1 | | [Brave Search](/brave-search) | `GET` | `/v2/brave/search` | 1 | | [Carrefour Product](/carrefour-product) | `GET` | `/v2/carrefour/product` | 2 | | [Carrefour Search](/carrefour-search) | `GET` | `/v2/carrefour/search` | 2 | | [Carrefour Suggest](/carrefour-suggest) | `GET` | `/v2/carrefour/suggest` | 1 | | [Cdiscount Product](/cdiscount-product) | `GET` | `/v2/cdiscount/product` | 2 | | [Cdiscount Product Offer](/cdiscount-product-offer) | `GET` | `/v2/cdiscount/product/offer` | 2 | | [Cdiscount Search](/cdiscount-search) | `GET` | `/v2/cdiscount/search` | 2 | | [Chewy Product](/chewy-product) | `GET` | `/v2/chewy/product` | 2 | | [Chewy Products Finder](/finder-chewy-products) | `GET` | `/v2/finder/chewy-products` | 0 | | [Chewy Search](/chewy-search) | `GET` | `/v2/chewy/search` | 2 | | [Company Database](/company) | `GET` | `/v2/company` | 1 | | [Crunchbase Company Info](/crunchbase-company-info) | `GET` | `/v2/crunchbase/company/info` | 2 | | [Crunchbase Event](/crunchbase-event) | `GET` | `/v2/crunchbase/event` | 2 | | [Crunchbase Funding Round](/crunchbase-funding-round) | `GET` | `/v2/crunchbase/funding_round` | 2 | | [Crunchbase Funding Rounds](/crunchbase-funding-rounds) | `GET` | `/v2/crunchbase/funding_rounds` | 2 | | [Crunchbase People Info](/crunchbase-people-info) | `GET` | `/v2/crunchbase/people/info` | 2 | | [Crunchbase Search](/crunchbase-search) | `GET` | `/v2/crunchbase/search` | 2 | | [Dataset Linkedin Company](/datasets-linkedin-company) | `POST` | `/v2/datasets/linkedin/company` | 1 | | [Domain DNSBL](/domain-dnsbl) | `GET` | `/v2/domain/dnsbl` | 1 | | [Domain Malicious](/domain-malicious) | `GET` | `/v2/domain/malicious` | 1 | | [Domain Whois](/domain-whois) | `GET` | `/v2/domain/whois` | 1 | | [E.Leclerc Product](/eleclerc-product) | `GET` | `/v2/eleclerc/product` | 1 | | [E.Leclerc Search](/eleclerc-search) | `GET` | `/v2/eleclerc/search` | 1 | | [E.Leclerc Suggest](/eleclerc-suggest) | `GET` | `/v2/eleclerc/suggest` | 1 | | [Eleclerc Stores Finder](/finder-eleclerc-stores) | `GET` | `/v2/finder/eleclerc-stores` | 0 | | [Email Analyzes](/email-analyzes) | `GET` | `/v2/email/analyzes` | 1 | | [Email Finder](/email-finder) | `GET` | `/v2/email/finder` | 1 | | [Email Verify](/email-verify) | `GET` | `/v2/email/verify` | 1 | | [Expedia Ad](/expedia-ad) | `GET` | `/v2/expedia/ad` | 2 | | [Expedia Search](/expedia-search) | `GET` | `/v2/expedia/search` | 2 | | [Fiverr Profile Info](/fiverr-profile-info) | `GET` | `/v2/fiverr/profile/info` | 1 | | [Fiverr Search](/fiverr-search) | `GET` | `/v2/fiverr/search` | 1 | | [G2 Product Info](/g2-product-info) | `GET` | `/v2/g2/product/info` | 2 | | [GitHub User Info](/github-user-info) | `GET` | `/v2/github/user/info` | 1 | | [Google Countries Finder](/finder-google-countries) | `GET` | `/v2/finder/google-countries` | 0 | | [Google Images](/google-images) | `GET` | `/v2/google/images` | 1 | | [Google Jobs](/google-jobs) | `GET` | `/v2/google/jobs` | 1 | | [Google Languages Finder](/finder-google-languages) | `GET` | `/v2/finder/google-languages` | 0 | | [Google Locations Finder](/finder-google-locations) | `GET` | `/v2/finder/google-locations` | 0 | | [Google News](/google-news) | `GET` | `/v2/google/news` | 1 | | [Google Search](/google-search) | `GET` | `/v2/google/search` | 1 | | [Google Search Autocomplete](/google-search-autocomplete) | `GET` | `/v2/google/search/autocomplete` | 1 | | [Google Videos](/google-videos) | `GET` | `/v2/google/videos` | 1 | | [Homestra Ad](/homestra-ad) | `GET` | `/v2/homestra/ad` | 1 | | [Homestra Search](/homestra-search) | `GET` | `/v2/homestra/search` | 1 | | [Indeed Company Info](/indeed-company-info) | `GET` | `/v2/indeed/company/info` | 2 | | [Instagram Post Info](/instagram-post-info) | `GET` | `/v2/instagram/post/info` | 1 | | [Instagram User Info](/instagram-user-info) | `GET` | `/v2/instagram/user/info` | 1 | | [Kick User Info](/kick-user-info) | `GET` | `/v2/kick/user/info` | 1 | | [Leboncoin Ad](/leboncoin-ad) | `GET` | `/v2/leboncoin/ad` | 1 | | [Leboncoin Search](/leboncoin-search) | `GET` | `/v2/leboncoin/search` | 1 | | [Leboncoin Search API](/leboncoin-search-api) | `POST` | `/v2/leboncoin/search_api` | 1 | | [Leroy Merlin Products Finder](/finder-leroymerlin-products) | `GET` | `/v2/finder/leroymerlin-products` | 0 | | [LinkedIn Company Info](/linkedin-company-info) | `GET` | `/v2/linkedin/company/info` | 1 | | [LinkedIn Industries Finder](/finder-linkedin-industries) | `GET` | `/v2/finder/linkedin-industries` | 0 | | [LinkedIn Job Count](/linkedin-job-count) | `GET` | `/v2/linkedin/job/count` | 1 | | [LinkedIn Job Info](/linkedin-job-info) | `GET` | `/v2/linkedin/job/info` | 1 | | [LinkedIn Job Search](/linkedin-job-search) | `GET` | `/v2/linkedin/job/search` | 1 | | [LinkedIn Job Suggest](/linkedin-job-suggest) | `GET` | `/v2/linkedin/job/suggest` | 1 | | [LinkedIn Post Info](/linkedin-post-info) | `GET` | `/v2/linkedin/post/info` | 1 | | [LinkedIn Product Info](/linkedin-product-info) | `GET` | `/v2/linkedin/product/info` | 1 | | [LinkedIn Profile Info](/linkedin-profile-info) | `GET` | `/v2/linkedin/profile/info` | 1 | | [ManoMano Product](/manomano-product) | `GET` | `/v2/manomano/product` | 1 | | [ManoMano Product Offer](/manomano-product-offer) | `GET` | `/v2/manomano/product/offer` | 1 | | [ManoMano Search](/manomano-search) | `GET` | `/v2/manomano/search` | 1 | | [Mascus Ad](/mascus-ad) | `GET` | `/v2/mascus/ad` | 1 | | [Mascus Search](/mascus-search) | `GET` | `/v2/mascus/search` | 1 | | [Oceanio Search](/oceanio-search) | `GET` | `/v2/oceanio/search` | 1 | | [Ovoko Ad](/ovoko-ad) | `GET` | `/v2/ovoko/ad` | 1 | | [Ovoko Search](/ovoko-search) | `GET` | `/v2/ovoko/search` | 1 | | [Owler Company Info](/owler-company-info) | `GET` | `/v2/owler/company/info` | 1 | | [Owler Search](/owler-search) | `GET` | `/v2/owler/search` | 1 | | [PagesJaunes Page Info](/pagesjaunes-page-info) | `GET` | `/v2/pagesjaunes/page/info` | 1 | | [PagesJaunes Search](/pagesjaunes-search) | `GET` | `/v2/pagesjaunes/search` | 1 | | [Pinterest User Info](/pinterest-user-info) | `GET` | `/v2/pinterest/user/info` | 1 | | [ProductHunt Product Info](/producthunt-product-info) | `GET` | `/v2/producthunt/product/info` | 1 | | [Rocketreack Company Info](/rocketreach-company-info) | `GET` | `/v2/rocketreach/company/info` | 1 | | [SeLoger Agency](/seloger-agency) | `GET` | `/v2/seloger/agency` | 2 | | [SeLoger Agency Rent](/seloger-agency-rent) | `GET` | `/v2/seloger/agency/rent` | 2 | | [SeLoger Agency Sale](/seloger-agency-sale) | `GET` | `/v2/seloger/agency/sale` | 2 | | [SeLoger Property](/seloger-property) | `GET` | `/v2/seloger/property` | 2 | | [SeLoger Search](/seloger-search) | `GET` | `/v2/seloger/search` | 2 | | [Shophouzz Product](/shophouzz-product) | `GET` | `/v2/shophouzz/product` | 1 | | [Shopify Apps](/shopify-apps) | `GET` | `/v2/shopify/apps` | 1 | | [Shopify Product](/shopify-product) | `GET` | `/v2/shopify/product` | 1 | | [SimilarWeb Domain](/similarweb-domain) | `GET` | `/v2/similarweb/domain` | 1 | | [Similarweb Search](/similarweb-search) | `GET` | `/v2/similarweb/search` | 1 | | [StockX Product](/stockx-product) | `GET` | `/v2/stockx/product` | 2 | | [StockX Search](/stockx-search) | `GET` | `/v2/stockx/search` | 2 | | [StockX Trends](/stockx-trends) | `GET` | `/v2/stockx/trends` | 2 | | [Trustpilot Company Info](/trustpilot-company-info) | `GET` | `/v2/trustpilot/company/info` | 1 | | [Usage](/usage) | `GET` | `/v2/usage` | 0 | | [Vinted User Info](/vinted-user-info) | `GET` | `/v2/vinted/user/info` | 1 | | [Walmart Product](/walmart-product) | `GET` | `/v2/walmart/product` | 1 | | [Website Crawler](/website-crawler) | `GET` | `/v2/website/crawler` | 1 | | [Website Email Phone Extractor](/website-email-phone-extractor) | `GET` | `/v2/website/email_phone_extractor` | 1 | | [Website Rendering](/website-rendering) | `GET` | `/v2/website/rendering` | 2 | | [Website Screenshot](/website-screenshot) | `GET` | `/v2/website/screenshot` | 2 | | [Website Technology](/website-technology) | `GET` | `/v2/website/technology` | 1 | | [Website WebUnlocker](/website-webunlocker) | `GET` | `/v2/website/webunlocker` | 3 | | [Weibo Post Info](/weibo-post-info) | `GET` | `/v2/weibo/post/info` | 1 | | [Weibo Search](/weibo-search) | `GET` | `/v2/weibo/search` | 1 | | [Wellfound Company Info](/wellfound-company-info) | `GET` | `/v2/wellfound/company/info` | 1 | # Crunchbase Company Info **GET** `https://api.piloterr.com/v2/crunchbase/company/info` Convert URLs into detailed Crunchbase profiles for immediate company insights. **Credit cost:** 2 credits per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | No | Search for a company by its name, permalink, or full Crunchbase URL. - `openai`: Search by company name or slug - `e8faa410-c307-482b-a389-74c6507ed242`: Search by UUID - `https://www.crunchbase.com/organization/openai`: Full Crunchbase organization URL **Note:** Mutually exclusive with `domain` — use one or the other, never both. **Example:** openai | | `domain` | query | `string` | No | Perform a reverse lookup by domain name to find the associated Crunchbase company profile. **Accepted formats:** - `piloterr.com`: Plain domain name - `https://piloterr.com`: Full URL with protocol **Note:** Mutually exclusive with `query` — use one or the other, never both. **Example:** piloterr.com | ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "logo": { "type": "string" }, "name": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "uuid": { "type": "string" }, "aliases": { "type": "array", "items": { "type": "string" } }, "founded": { "type": "string" }, "website": { "type": "string" }, "headline": { "type": "string" }, "location": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" }, "uuid": { "type": "string" }, "permalink": { "type": "string" } } } }, "permalink": { "type": "string" }, "categories": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "uuid": { "type": "string" }, "permalink": { "type": "string" } } } }, "description": { "type": "string" }, "company_type": { "type": "string" }, "phone_number": { "type": "string" }, "employee_count": { "type": "string" }, "semrush_summary": { "type": "object", "properties": { "semrush_global_rank": { "type": "integer" }, "semrush_visits_latest_month": { "type": "integer" } } }, "social_networks": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "name": { "type": "string" } } } }, "operating_status": { "type": "string" }, "funding_rounds_headline": { "type": "object", "properties": { "funding_total": { "type": "object", "properties": { "value": { "type": "integer" }, "currency": { "type": "string" }, "value_usd": { "type": "integer" } } }, "num_funding_rounds": { "type": "integer" } } }, "company_financials_highlights": { "type": "object", "properties": { "num_exits": { "type": "integer" }, "num_funds": { "type": "integer" }, "funding_total": { "type": "object", "properties": { "value": { "type": "integer" }, "currency": { "type": "string" }, "value_usd": { "type": "integer" } } }, "num_investors": { "type": "integer" }, "num_investments": { "type": "integer" }, "num_funding_rounds": { "type": "integer" }, "num_lead_investors": { "type": "integer" }, "num_lead_investments": { "type": "integer" } } } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # Crunchbase Event **GET** `https://api.piloterr.com/v2/crunchbase/event` Retrieve detailed Crunchbase event profiles with speakers, sponsors, exhibitors, and press timelines. **Status:** Degraded **Credit cost:** 2 credits per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | Retrieve event data using its Crunchbase permalink or full URL. - `london-tech-week-2025`: Event permalink slug - `https://www.crunchbase.com/event/london-tech-week-2025`: Full Crunchbase event URL **Note:** The permalink is the last segment of the Crunchbase event URL. **Example:** london-tech-week-2025 | ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "logo": { "type": "string" }, "name": { "type": "string" }, "uuid": { "type": "string" }, "title": { "type": "string" }, "ends_on": { "type": "string" }, "starts_on": { "type": "string" }, "description": { "type": "string" }, "short_description": { "type": "string" }, "event_type": { "type": "array", "items": { "type": "string" } }, "num_speakers": { "type": "integer" }, "num_sponsors": { "type": "integer" }, "num_exhibitors": { "type": "integer" }, "num_contestants": { "type": "integer" }, "categories": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "uuid": { "type": "string" }, "image_id": { "type": "string" }, "permalink": { "type": "string" } } } }, "speakers": { "type": "array", "items": { "type": "object", "properties": { "logo": { "type": "string" }, "name": { "type": "string" }, "uuid": { "type": "string" }, "job_title": { "type": "string" }, "permalink": { "type": "string" }, "organization": { "type": "object", "properties": { "logo": { "type": "string" }, "name": { "type": "string" }, "uuid": { "type": "string" }, "permalink": { "type": "string" } } } } } }, "sponsors": { "type": "array", "items": { "type": "object", "properties": { "logo": { "type": "string" }, "name": { "type": "string" }, "uuid": { "type": "string" }, "permalink": { "type": "string" }, "short_description": { "type": "string" } } } }, "timeline": { "type": "object", "properties": { "count": { "type": "integer" }, "events": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "date": { "type": "string" }, "type": { "type": "string" }, "uuid": { "type": "string" }, "title": { "type": "string" }, "publisher": { "type": "string" } } } } } }, "is_locked": { "type": "boolean" }, "registration_url": { "type": "string" } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # Crunchbase Funding Round **GET** `https://api.piloterr.com/v2/crunchbase/funding_round` Retrieve full details of a specific Crunchbase funding round including investors and press timeline. **Credit cost:** 2 credits per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | The permalink of the specific funding round to retrieve. This is the unique identifier found in the Crunchbase funding round URL. **How to find the permalink:** Navigate to the funding round page on Crunchbase — the permalink is the last path segment of the URL. **Example:** openai-secondary-market--3bab6e98 **Notes:** - Double dashes (`--`) separate the organization name from the round UUID suffix. - You can retrieve funding round permalinks from the `crunchbase/funding_rounds` endpoint. | ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "uuid": { "type": "string" }, "value": { "type": "string" }, "image_id": { "type": "string" }, "permalink": { "type": "string" }, "entity_def_id": { "type": "string" }, "num_investors": { "type": "integer" }, "overview_fields_v2": { "type": "object", "properties": { "investment_type": { "type": "string" }, "preview_properties": { "type": "object", "properties": { "announced_on": { "type": "object", "properties": { "is_present": { "type": "boolean" } } }, "money_raised": { "type": "object", "properties": { "is_present": { "type": "boolean" } } } } }, "funded_organization_identifier": { "type": "object", "properties": { "role": { "type": "string" }, "uuid": { "type": "string" }, "value": { "type": "string" }, "image_id": { "type": "string" }, "permalink": { "type": "string" }, "entity_def_id": { "type": "string" } } } } }, "cards": { "type": "object", "properties": { "investors_headline": { "type": "object", "properties": { "num_investors": { "type": "integer" } } }, "investors_list": { "type": "array", "items": { "type": "object", "properties": { "identifier": { "type": "object", "properties": { "uuid": { "type": "string" }, "value": { "type": "string" }, "permalink": { "type": "string" }, "entity_def_id": { "type": "string" } } }, "investor_identifier": { "type": "object", "properties": { "uuid": { "type": "string" }, "value": { "type": "string" }, "image_id": { "type": "string" }, "permalink": { "type": "string" }, "entity_def_id": { "type": "string" } } } } } }, "lead_investors_image_list": { "type": "array", "items": {} }, "timeline": { "type": "object", "properties": { "count": { "type": "integer" }, "entities": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string" }, "properties": { "type": "object", "properties": { "identifier": { "type": "object", "properties": { "uuid": { "type": "string" }, "value": { "type": "string" }, "entity_def_id": { "type": "string" } } }, "activity_date": { "type": "string" }, "entity_def_id": { "type": "string" }, "activity_entities": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string" }, "value": { "type": "string" }, "image_id": { "type": "string" }, "permalink": { "type": "string" }, "entity_def_id": { "type": "string" } } } } } } } } } } } } } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # Crunchbase Funding Rounds **GET** `https://api.piloterr.com/v2/crunchbase/funding_rounds` Monitor funding history and financial milestones of companies with Crunchbase data. **Status:** Degraded **Credit cost:** 2 credits per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `days_since_announcement` | query | `number` | No | Filter funding rounds announced within the last N days. **Note:** The response returns a maximum of **15 results per request**. If `total` exceeds 15, combine with `investment_type` filters to paginate across rounds. **Example:** 30 | | `investment_type` | query | `string` | No | Filter by funding round type. Accepted values: - `pre_seed`, `seed`, `series_a`, `series_b`, `series_c`, `series_d`, `series_e`, `series_f`, `series_g`, `series_h`, `series_i`, `series_j`, `series_unknown`, `angel`, `private_equity`, `debt_financing`, `convertible_note`, `grant`, `corporate_round`, `equity_crowdfunding`, `product_crowdfunding`, `secondary_market`, `post_ipo_equity`, `post_ipo_debt`, `post_ipo_secondary`, `non_equity_assistance`, `initial_coin_offering`, `undisclosed` **Example:** seed | | `investor_identifiers` | query | `string` | No | Filter rounds by a specific investor using their Crunchbase UUID. **How to find an investor UUID:** Use the `crunchbase/company/info` or `crunchbase/people/info` endpoints to retrieve the `uuid` of the target investor. **Example:** df14597c-3e51-8d58-9c15-fb3de3a34a54 | | `funded_organization_identifier` | query | `string` | No | Filter rounds by a specific funded organization using their Crunchbase UUID. **How to find an organization UUID:** Use the `crunchbase/company/info` endpoint and read the `uuid` field from the response. **Example:** cf2c678c-b81a-80c3-10d1-9c5e76448e51 | ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "total": { "type": "integer" }, "results": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string" }, "identifier": { "type": "object", "properties": { "uuid": { "type": "string" }, "value": { "type": "string" }, "image_id": { "type": "string" }, "permalink": { "type": "string" }, "entity_def_id": { "type": "string" } } }, "investment_type": { "type": "string" }, "investor_identifiers": { "type": "array", "items": {} }, "funded_organization_identifier": { "type": "object", "properties": { "role": { "type": "string" }, "uuid": { "type": "string" }, "value": { "type": "string" }, "image_id": { "type": "string" }, "permalink": { "type": "string" }, "entity_def_id": { "type": "string" } } } } } } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # Crunchbase People Info **GET** `https://api.piloterr.com/v2/crunchbase/people/info` Retrieve detailed Crunchbase profiles for individuals including career history, investments, and board positions. **Credit cost:** 2 credits per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | Search for a person by their name, Crunchbase permalink, or full Crunchbase profile URL. - `elon-musk`: Search by permalink slug - `https://www.crunchbase.com/person/elon-musk`: Full Crunchbase person URL - `Sam Altman`: Search by full name **Example:** elon-musk | ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "logo": { "type": "string" }, "name": { "type": "string" }, "uuid": { "type": "string" }, "title": { "type": "string" }, "gender": { "type": "string" }, "image_id": { "type": "string" }, "permalink": { "type": "string" }, "short_description": { "type": "string" }, "num_current_jobs": { "type": "integer" }, "num_founded_organizations": { "type": "integer" }, "rank_principal_investor": { "type": "integer" }, "locations": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" }, "uuid": { "type": "string" }, "permalink": { "type": "string" } } } }, "current_positions": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "job_uuid": { "type": "string" }, "organization": { "type": "object", "properties": { "logo": { "type": "string" }, "name": { "type": "string" }, "uuid": { "type": "string" }, "permalink": { "type": "string" } } } } } }, "past_positions": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "ended_on": { "type": "object", "properties": { "value": { "type": "string" }, "precision": { "type": "string" } } }, "job_uuid": { "type": "string" }, "started_on": { "type": "object", "properties": { "value": { "type": "string" }, "precision": { "type": "string" } } }, "organization": { "type": "object", "properties": { "name": { "type": "string" }, "uuid": { "type": "string" }, "permalink": { "type": "string" } } } } } }, "education": { "type": "array", "items": { "type": "object", "properties": { "school": { "type": "object", "properties": { "logo": { "type": "string" }, "name": { "type": "string" }, "uuid": { "type": "string" }, "permalink": { "type": "string" } } }, "started_on": { "nullable": true }, "degree_name": { "nullable": true }, "completed_on": { "nullable": true }, "education_uuid": { "type": "string" } } } }, "social_networks": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "name": { "type": "string" } } } }, "investments": { "type": "array", "items": {} }, "facet_ids": { "type": "array", "items": { "type": "string" } } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # Crunchbase Search **GET** `https://api.piloterr.com/v2/crunchbase/search` Search Crunchbase for companies and people by keyword and retrieve their profiles and Crunchbase identifiers. **Credit cost:** 2 credits per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | The search keyword or phrase to query across Crunchbase. Searches both organizations and people. **Examples:** - `openai`: Search by company name - `elon`: Search by person or company name - `fintech london`: Multi-word search **Note:** The response includes both `organization` and `person` type results. Use the `type` field in each result to distinguish them. **Example:** openai | ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "logo": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "uuid": { "type": "string" }, "image_id": { "type": "string" }, "permalink": { "type": "string" }, "description": { "type": "string" } } } } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # Dataset Linkedin Company **POST** `https://api.piloterr.com/v2/datasets/linkedin/company` **Credit cost:** 1 credit per row ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "hits": { "type": "array", "items": { "type": "object", "properties": { "_id": { "type": "string" }, "_type": { "type": "string" }, "_index": { "type": "string" }, "_score": { "type": "integer" }, "_source": { "type": "object", "properties": { "name": { "type": "string" }, "domain": { "type": "string" }, "founded": { "type": "integer" }, "tagline": { "type": "string" }, "website": { "type": "string" }, "industry": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "description": { "type": "string" }, "staff_count": { "type": "integer" }, "staff_range": { "type": "string" }, "linkedin_url": { "type": "string" }, "locations_list": { "type": "array", "items": {} }, "last_crawled_at": { "type": "string" }, "headquarter_city": { "nullable": true }, "headquarter_line1": { "nullable": true }, "linkedin_id_alpha": { "type": "string" }, "specialities_list": { "type": "array", "items": { "type": "string" } }, "headquarter_country": { "nullable": true }, "linkedin_id_numeric": { "type": "integer" }, "headquarter_postal_code": { "nullable": true } } } } } }, "total": { "type": "integer" }, "max_score": { "type": "integer" } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # Domain DNSBL **GET** `https://api.piloterr.com/v2/domain/dnsbl` Check if a domain or IP address is listed in DNS-based blacklists (DNSBL), with detailed provider-level detection and category information. **Credit cost:** 1 credit per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | A domain name or IP address to check against DNS-based blacklists (DNSBL). **Examples:** 185.122.10.10 The API checks the input against hundreds of DNSBL providers and returns whether it has been blacklisted, along with the list of detecting providers and their categories. **Note:** Both IPv4 addresses and domain names are accepted. | ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "address": { "type": "string" }, "detected": { "type": "object", "properties": { "count": { "type": "integer" }, "providers": { "type": "array", "items": { "type": "string" } }, "categories": { "type": "object", "properties": { "dbl.spamhaus.org": { "type": "array", "items": { "type": "string" } }, "peer.asn.cymru.com": { "type": "array", "items": { "type": "string" } }, "origin.asn.cymru.com": { "type": "array", "items": { "type": "string" } }, "spambot.bls.digibase.ca": { "type": "array", "items": { "type": "string" } }, "abuse-contacts.abusix.org": { "type": "array", "items": { "type": "string" } } } } } }, "providers": { "type": "object", "properties": { "failed": { "type": "array", "items": { "type": "string" } }, "domains": { "type": "array", "items": { "type": "string" } }, "failed_count": { "type": "integer" }, "domains_count": { "type": "integer" } } }, "blacklisted": { "type": "boolean" } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # Domain Malicious **GET** `https://api.piloterr.com/v2/domain/malicious` Check if a domain or IP address has been flagged as malicious across multiple threat intelligence feeds, with source attribution. **Credit cost:** 1 credit per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | A domain name or IP address to check for malicious activity across multiple threat intelligence sources. **Examples:** 197.33.189.70 malicious-domain.com The API cross-references the input against community-curated threat feeds and returns whether it has been flagged as malicious, along with the specific sources that reported it. **Note:** Both IPv4 addresses and domain names are accepted. | ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "sources": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" } } } }, "malicious": { "type": "boolean" } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # Domain Whois **GET** `https://api.piloterr.com/v2/domain/whois` Retrieve WHOIS registration data for any domain, including registration dates, registrar details, name servers, and contact information. **Credit cost:** 1 credit per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | A domain name for which you want to retrieve WHOIS registration information. **Example:** piloterr.com The API returns full WHOIS data including domain registration dates, registrar details, name servers, and contact information (where not redacted for privacy). **Note:** Privacy protection (GDPR redaction) may hide registrant details for many domains. | ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "domain": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "domain": { "type": "string" }, "status": { "type": "array", "items": { "type": "string" } }, "punycode": { "type": "string" }, "extension": { "type": "string" }, "created_date": { "type": "string" }, "name_servers": { "type": "array", "items": { "type": "string" } }, "updated_date": { "type": "string" }, "whois_server": { "type": "string" }, "expiration_date": { "type": "string" }, "created_date_in_time": { "type": "string" }, "updated_date_in_time": { "type": "string" }, "expiration_date_in_time": { "type": "string" } } }, "registrar": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "referral_url": { "type": "string" } } }, "technical": { "type": "object", "properties": { "fax": { "type": "string" }, "city": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "street": { "type": "string" }, "country": { "type": "string" }, "organization": { "type": "string" } } }, "registrant": { "type": "object", "properties": { "fax": { "type": "string" }, "city": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "street": { "type": "string" }, "country": { "type": "string" } } }, "administrative": { "type": "object", "properties": { "fax": { "type": "string" }, "city": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "country": { "type": "string" }, "organization": { "type": "string" } } } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # E.Leclerc Product **GET** `https://api.piloterr.com/v2/eleclerc/product` Retrieve detailed product information from E.Leclerc by EAN barcode, including price, stock status, offers, and product attributes. **Credit cost:** 1 credit per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | E.Leclerc product EAN (European Article Number) to look up. **Example:** 3603312946485 **Notes:** - The EAN must be a valid 13-digit barcode identifier for a product listed on the E.Leclerc online store. - If no `store_id` is provided, the product is looked up on the national online store. - The response includes pricing, stock, offer details, and product attributes. | | `store_id` | query | `string` | No | ID of the specific E.Leclerc store to fetch the product from. Get the `store_id` from the [E.Leclerc Stores](https://docs.piloterr.com/finder-eleclerc-stores) API. **Example:** 1631 **Notes:** - If omitted, the product data is fetched from the national online store. - Use a store ID to retrieve local pricing and stock for a specific physical location. | ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "ean": { "type": "string" }, "brand": { "nullable": true }, "image": { "type": "string" }, "offer": { "type": "object", "properties": { "price": { "type": "object", "properties": { "price": { "type": "number" }, "is_nx_c_b": { "type": "boolean" }, "private_copy": { "type": "integer" }, "eco_contribution": { "type": "integer" }, "availability_status": { "type": "string" }, "eco_contribution_mobilier": { "type": "integer" }, "offer_availability_status": { "type": "string" } } }, "stimuli": { "type": "object", "properties": {} }, "elected_offer": { "type": "object", "properties": { "slug": { "type": "string" }, "stock": { "type": "integer" }, "shop_id": { "type": "integer" }, "shop_name": { "type": "string" }, "offer_type": { "type": "string" }, "is_cross_dock": { "type": "boolean" }, "national_offer_id": { "type": "string" }, "is_leclerc_national_and_local": { "type": "boolean" }, "is_active_promotion_without_stock": { "type": "boolean" } } }, "stimuli_picto": { "type": "object", "properties": {} }, "category_picto": { "type": "string" }, "cnc_offers_count": { "type": "integer" }, "other_offers_count": { "type": "integer" } } }, "title": { "type": "string" }, "data_layer": { "type": "object", "properties": { "id": { "type": "string" }, "ean": { "type": "string" }, "name": { "type": "string" }, "price": { "type": "string" }, "vendor": { "type": "string" }, "section": { "type": "string" }, "category": { "type": "string" }, "in_stock": { "type": "boolean" }, "condition": { "type": "string" }, "currency_code": { "type": "string" } } }, "rating_count": { "type": "integer" }, "rating_average": { "type": "number" } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # E.Leclerc Search **GET** `https://api.piloterr.com/v2/eleclerc/search` Search for products on E.Leclerc by keyword with optional store-specific filtering and pagination. **Credit cost:** 1 credit per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | Search keyword or phrase to query on E.Leclerc. **Example:** pomme **Notes:** - Supports any keyword, brand name, or product category (in French). - Results are paginated; use the `page` parameter to navigate through pages. | | `store_id` | query | `string` | No | ID of a specific E.Leclerc store to search in. Get the `store_id` from the [E.Leclerc Stores](https://docs.piloterr.com/finder-eleclerc-stores) API. **Example:** 1631 **Notes:** - If omitted, the search is performed on the national online store. - Use a store ID to get local product availability and pricing. | | `page` | query | `number` | No | Page number for paginated results. **Notes:** - Use the `pagination.next` field in the response to determine if additional pages are available. - Increment this value to retrieve subsequent result pages. | ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "total": { "type": "integer" }, "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "sku": { "type": "string" }, "slug": { "type": "string" }, "label": { "type": "string" }, "family": { "type": "object", "properties": { "code": { "type": "string" }, "label": { "type": "string" }, "logisticClassCode": { "type": "string" } } }, "variants": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "sku": { "type": "string" }, "slug": { "type": "string" }, "label": { "type": "string" }, "offers": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "shop": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "signCode": { "type": "string" } } }, "stock": { "type": "integer" }, "locale": { "type": "string" }, "ranges": { "type": "array", "items": { "type": "object", "properties": { "price": { "type": "object", "properties": { "price": { "type": "integer" }, "priceWithAllTaxes": { "type": "integer" } } }, "threshold": { "type": "integer" } } } }, "currency": { "type": "object", "properties": { "code": { "type": "string" }, "symbol": { "type": "string" } } }, "isDefault": { "type": "boolean" }, "externalId": { "type": "string" } } } }, "offersTotal": { "type": "integer" } } } }, "creationDate": { "type": "string" }, "cncOffersCount": { "type": "integer" }, "lastUpdateDate": { "type": "string" } } } }, "pagination": { "type": "object", "properties": { "next": { "type": "integer" }, "current": { "type": "integer" }, "has_next_page": { "type": "boolean" } } } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # E.Leclerc Suggest **GET** `https://api.piloterr.com/v2/eleclerc/suggest` Get instant product autocomplete suggestions from E.Leclerc for a given keyword or EAN. **Credit cost:** 1 credit per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | Search term or EAN to get product suggestions for. Accepted input types: - `keyword`: partial product name or category (e.g. `pomme`) - `EAN`: full product barcode (e.g. `9782330149635`) **Example:** pomme **Notes:** - Returns up to 6 autocomplete suggestions matching the query. - Each suggestion includes the product URL, slug, title, subtitle (author/brand), and image URL. - This endpoint mirrors the E.Leclerc website autocomplete search box. | ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "slug": { "type": "string" }, "title": { "type": "string" }, "subtitle": { "type": "string" }, "image_url": { "type": "string" } } } } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # Email Analyzes **GET** `https://api.piloterr.com/v2/email/analyzes` Analyze a domain to retrieve its email infrastructure — Microsoft 365 and Google Workspace domains, SPF records, and DNS configurations. **Credit cost:** 1 credit per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | The domain name you want to analyze for email infrastructure. **Example:** airbus.com The API will return all associated Microsoft 365 and Google Workspace domains, along with SPF records and DNS configurations. **Note:** Provide a bare domain (e.g. `airbus.com`), not a full URL. | ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "domains": { "type": "object", "properties": { "airbus.com": { "type": "array", "items": { "type": "string" } }, "apsys-airbus.com": { "type": "array", "items": { "type": "string" } }, "airbus.onmicrosoft.com": { "type": "array", "items": { "type": "string" } }, "globalemail.airbus.com": { "type": "array", "items": {} }, "airbus.mail.onmicrosoft.com": { "type": "array", "items": { "type": "string" } } } }, "is_microsoft_365": { "type": "boolean" }, "is_google_workspace": { "type": "boolean" }, "microsoft_365_domains": { "type": "array", "items": { "type": "string" } }, "google_workspace_domains": { "type": "array", "items": {} } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # Email Finder **GET** `https://api.piloterr.com/v2/email/finder` Find verified professional email addresses by combining a person's full name with their company domain or company name. **Credit cost:** 1 credit per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | Full name of the person whose professional email address you want to find. **Example:** Rémi Agosta **Note:** Provide the full name as accurately as possible for the best results. Common name variations are supported. | | `company_domain` | query | `string` | No | The company's domain name. Multiple formats are accepted: - `piloterr.com`: Bare domain (preferred) - `https://www.piloterr.com`: Full URL format **Note:** At least one of `company_domain` or `company_name` is required. If both are omitted, the API returns a `400` error. | | `company_name` | query | `string` | No | The company name of the person you are looking for. **Example:** Piloterr **Note:** At least one of `company_domain` or `company_name` is required. `company_domain` is preferred when available as it produces more accurate results. | ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "email": { "type": "string" }, "status": { "type": "string" }, "last_name": { "type": "string" }, "first_name": { "type": "string" }, "company_domain": { "type": "string" } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # Email Verify **GET** `https://api.piloterr.com/v2/email/verify` Verify whether an email address is valid and deliverable, returning a clear status to prevent bounces and maintain list hygiene. **Credit cost:** 1 credit per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | The email address you want to verify. **Example:** remi.agosta@piloterr.com **Note:** Provide the full email address including the domain. The API checks deliverability and returns `valid`, `invalid`, or `unknown` as the status. | ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "email": { "type": "string" }, "status": { "type": "string" } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # Error Handling Every request to the Piloterr API returns a standard HTTP status code. This guide covers what each code means, when credits are consumed, and how to handle failures in your integration. Response format [#response-format] Successful responses return a JSON object with the data for that endpoint. Error responses follow a consistent structure: ```json { "error": "Human-readable description of what went wrong" } ``` Always check the HTTP status code **before** reading the body. *** Status codes [#status-codes] 200 Success [#200-success] **Billed.** The request completed successfully. Credits are deducted from your balance. ```typescript const res = await fetch(url, { headers: { "x-api-key": API_KEY } }) if (res.status === 200) { const data = await res.json() // process data } ``` 201 Job Created [#201-job-created] **Billed.** An asynchronous job was created and accepted. Credits are deducted immediately when the job is queued. 202 Accepted (async) [#202-accepted-async] **Not billed yet.** The request was accepted and queued for processing. Use the returned job ID to poll for the result. Credits are only billed when the job completes successfully. 400 Bad Request [#400-bad-request] **Not billed.** Your request contains invalid or missing parameters. **Common causes:** * A required query parameter is missing * A parameter value has the wrong type or format * The request body is malformed **What to do:** Re-read the endpoint documentation and verify every required parameter. Log the full request URL to spot typos. ```typescript if (res.status === 400) { const { error } = await res.json() console.error("Bad request:", error) // do not retry, fix the parameters first } ``` 401 Unauthorized [#401-unauthorized] **Not billed.** Returned for authentication issues **and** rate limiting. Check the error message to distinguish between them. Your `x-api-key` header is missing or contains an unrecognized value. **Fix:** Copy your key from your [dashboard → API Keys](https://app.piloterr.com) and make sure the `x-api-key` header is present on every request. The key exists but has been deactivated. **Fix:** Go to your [dashboard → API Keys](https://app.piloterr.com) and activate the key, or generate a new one. The key has passed its expiry date. **Fix:** Generate a new key or extend the expiry from your dashboard. You have sent too many requests in a short window. **Fix:** Back off and retry after a delay. If you hit this regularly, consider upgrading your plan. ```typescript if (res.status === 401) { const { error } = await res.json() if (error.toLowerCase().includes("rate limit")) { await new Promise(r => setTimeout(r, 2000)) // retry } } ``` 402 Payment Required [#402-payment-required] **Not billed.** Your credit balance is empty. The request was not executed. **What to do:** 1. Top up your balance from your [dashboard](https://app.piloterr.com). 2. Or enable [Auto Top-Up](/auto-top-up) to prevent this from happening again. Auto Top-Up only triggers when your balance drops below the configured threshold. It never runs on a fixed schedule or at a specific time. A built-in **72-hour cooldown** also prevents multiple charges in a short period: once a top-up fires, it cannot trigger again for 72 hours regardless of how your balance moves. If a charge fails, Auto Top-Up is automatically disabled to protect your account. Do not retry a `402` response immediately. The call will fail again until you add credits. Set up an alert so your team is notified when this happens. ```typescript if (res.status === 402) { // alert your team or trigger an auto top-up flow throw new Error("Insufficient credits. Top up at https://app.piloterr.com") } ``` 403 Forbidden [#403-forbidden] **Not billed.** Your key does not have permission to access this endpoint. **What to do:** Verify that your key's permissions cover the endpoint you are calling. Contact support if you believe this is a mistake. 404 Not Found [#404-not-found] **May be billed** (endpoint-specific). The resource was not found. Check the individual endpoint documentation to confirm whether this response is charged. ```typescript if (res.status === 404) { // handle "no result" gracefully, not as a fatal error return null } ``` 500 Internal Server Error [#500-internal-server-error] **Not billed.** An unexpected error occurred on our side. **What to do:** Retry with exponential backoff. If the issue persists, contact support. ```typescript async function fetchWithRetry(url: string, options: RequestInit, maxRetries = 3) { for (let attempt = 0; attempt <= maxRetries; attempt++) { const res = await fetch(url, options) if (res.status !== 500 || attempt === maxRetries) return res const delay = 500 * 2 ** attempt console.warn(`500 error, retrying in ${delay}ms (attempt ${attempt + 1}/${maxRetries})`) await new Promise(r => setTimeout(r, delay)) } } ``` *** Complete error handler [#complete-error-handler] A single function that covers every status code: ```typescript interface ApiResult { data: T | null error: string | null status: number billed: boolean } async function apiCall(url: string, apiKey: string): Promise> { const res = await fetch(url, { headers: { "x-api-key": apiKey }, }) // 200 and 201 are always billed; 404 billing is endpoint-specific const billed = res.status === 200 || res.status === 201 if (res.status === 200) { return { data: await res.json() as T, error: null, status: 200, billed } } const body = await res.json().catch(() => ({ error: "Unknown error" })) const error = body?.error ?? "Unknown error" switch (res.status) { case 400: console.error("[400] Bad request, fix your parameters:", error) break case 401: if (error.toLowerCase().includes("rate limit")) { console.warn("[401] Rate limit, back off and retry") } else { console.error("[401] Auth error, check your API key:", error) } break case 402: console.error("[402] No credits remaining. Top up at https://app.piloterr.com") break case 403: console.error("[403] Forbidden, check your key permissions") break case 404: console.warn("[404] Not found, no result for this request") break case 500: console.error("[500] Server error, retry with backoff") break default: console.error(`[${res.status}] Unexpected status:`, error) } return { data: null, error, status: res.status, billed } } ``` *** Retry strategy [#retry-strategy] | Status | Retry? | Strategy | | ------------------ | ------ | ------------------------------------ | | `400` | No | Fix the request first | | `401` (rate limit) | Yes | Wait 2–5 s, then retry | | `401` (auth) | No | Fix the API key | | `402` | No | Add credits first | | `403` | No | Check permissions | | `404` | No | Handle as empty result | | `500` | Yes | Exponential backoff (max 3 attempts) | *** Billing summary [#billing-summary] | Status | Billed | | --------------- | ------------------------------------------- | | `200` | Yes | | `201` | Yes | | `404` | Endpoint-specific (check the endpoint docs) | | All other codes | No | See the [Credits](/credits) page for a full cost breakdown per endpoint. For broader integration advice, see [Best Practices](/best-practices). # Expedia Ad **GET** `https://api.piloterr.com/v2/expedia/ad` **Status:** Maintenance **Credit cost:** 2 credits per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | | ## Responses ### 200 Successful response ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # Expedia Search **GET** `https://api.piloterr.com/v2/expedia/search` Execute a hotel search on Expedia using a direct search URL and receive structured hotel listings with prices, ratings, and availability. **Credit cost:** 2 credits per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | A valid Expedia hotel search URL. Copy the URL directly from your Expedia search results page. **Example:** https://euro.expedia.net/Hotel-Search?currency=EUR&siteid=4400&destination=Toulouse **Notes:** - The URL must be a valid Expedia or Euro Expedia hotel search URL. - You can customize filters (dates, currency, location, guests) directly in the URL before passing it. - International Expedia domains (e.g., `euro.expedia.net`) are supported. | ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "location": { "type": "string" }, "room_info": { "type": "string" }, "taxes_info": { "type": "string" }, "description": { "type": "string" }, "rating_text": { "type": "string" }, "star_rating": { "type": "integer" }, "is_sponsored": { "type": "boolean" }, "rating_score": { "type": "number" }, "current_price": { "type": "integer" }, "reviews_count": { "type": "integer" }, "discount_badge": { "nullable": true }, "special_offers": { "type": "array", "items": { "type": "string" } }, "taxes_included": { "type": "boolean" }, "rating_category": { "type": "string" }, "current_price_text": { "type": "string" } } } } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # Chewy Products Finder **GET** `https://api.piloterr.com/v2/finder/chewy-products` Find Chewy product URLs by product name, ID, or any combination of filters to use in product detail and rendering API calls. ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `search` | query | `string` | No | Free-text search across product titles and IDs. Optional if at least one filter is provided. **Example:** dog food | | `query` | query | `string` | No | Legacy alias of `search`. Kept for backward compatibility. | | `id` | query | `string` | No | Filter by one or several internal product IDs. Provide a comma-separated list to match multiple IDs. **Example:** 312253,312254 | | `domain` | query | `string` | No | Filter by website domain. Comma-separated values are accepted. **Example:** com | | `filter` | query | `string` | No | Raw filter expression for advanced filtering. Combined with the shorthand filters using `AND`. **Example:** domain = "com" AND title CONTAINS "puppy" | | `limit` | query | `number` | No | Maximum number of results to return. Default is 10, maximum is 100. | | `offset` | query | `number` | No | Number of results to skip for pagination. Default is 0. | | `sort` | query | `string` | No | Sort the results. Provide one or several attributes with `:asc` or `:desc`, comma-separated. **Example:** title:asc | | `fields` | query | `string` | No | Comma-separated list of fields to return. Defaults to all fields. **Example:** id,title,url | | `count` | query | `boolean` | No | When `true`, the response is wrapped in an object containing the total estimated count plus the hits: `{ count, hits }`. When `false` or omitted, returns the raw hits array. **Example:** true | ## Responses ### 200 Successful response ```json { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "title": { "type": "string" }, "domain": { "type": "string" } } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # Eleclerc Stores Finder **GET** `https://api.piloterr.com/v2/finder/eleclerc-stores` Search Eleclerc stores by name or city to retrieve contact details, opening hours, and geolocation. ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | Filters stores based on a search string. The search is **non-case-sensitive** and returns all stores whose names contain the specified string. **Example:** paris | ## Responses ### 200 Successful response ```json { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "store_id": { "type": "string" }, "name": { "type": "string" }, "contact": { "type": "object", "properties": { "email": { "nullable": true }, "phone": { "type": "string" } } }, "address": { "type": "object", "properties": { "lines": { "type": "array", "items": { "type": "string" } }, "country_code": { "nullable": true }, "city": { "type": "string" }, "zipcode": { "type": "string" } } }, "weekly_opening": { "type": "object", "properties": { "1": { "type": "object", "properties": { "hours": { "type": "array", "items": { "type": "object", "properties": { "end": { "type": "string" }, "start": { "type": "string" } } } }, "isSpecial": { "type": "boolean" } } }, "2": { "type": "object", "properties": { "hours": { "type": "array", "items": { "type": "object", "properties": { "end": { "type": "string" }, "start": { "type": "string" } } } }, "isSpecial": { "type": "boolean" } } }, "3": { "type": "object", "properties": { "hours": { "type": "array", "items": { "type": "object", "properties": { "end": { "type": "string" }, "start": { "type": "string" } } } }, "isSpecial": { "type": "boolean" } } }, "4": { "type": "object", "properties": { "hours": { "type": "array", "items": { "type": "object", "properties": { "end": { "type": "string" }, "start": { "type": "string" } } } }, "isSpecial": { "type": "boolean" } } }, "5": { "type": "object", "properties": { "hours": { "type": "array", "items": { "type": "object", "properties": { "end": { "type": "string" }, "start": { "type": "string" } } } }, "isSpecial": { "type": "boolean" } } }, "6": { "type": "object", "properties": { "hours": { "type": "array", "items": { "type": "object", "properties": { "end": { "type": "string" }, "start": { "type": "string" } } } }, "isSpecial": { "type": "boolean" } } }, "7": { "type": "object", "properties": { "hours": { "type": "array", "items": { "type": "object", "properties": { "end": { "type": "string" }, "start": { "type": "string" } } } }, "isSpecial": { "type": "boolean" } } }, "timezone": { "type": "string" } } }, "opening_hours": { "type": "object", "properties": { "usual": { "type": "object", "properties": { "1": { "type": "array", "items": { "type": "object", "properties": { "end": { "type": "string" }, "start": { "type": "string" } } } }, "2": { "type": "array", "items": { "type": "object", "properties": { "end": { "type": "string" }, "start": { "type": "string" } } } }, "3": { "type": "array", "items": { "type": "object", "properties": { "end": { "type": "string" }, "start": { "type": "string" } } } }, "4": { "type": "array", "items": { "type": "object", "properties": { "end": { "type": "string" }, "start": { "type": "string" } } } }, "5": { "type": "array", "items": { "type": "object", "properties": { "end": { "type": "string" }, "start": { "type": "string" } } } }, "6": { "type": "array", "items": { "type": "object", "properties": { "end": { "type": "string" }, "start": { "type": "string" } } } }, "7": { "type": "array", "items": { "type": "object", "properties": { "end": { "type": "string" }, "start": { "type": "string" } } } } } }, "timezone": { "type": "string" } } }, "geometry": { "type": "object", "properties": { "type": { "type": "string" }, "coordinates": { "type": "array", "items": { "type": "number" } } } } } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # Google Countries Finder **GET** `https://api.piloterr.com/v2/finder/google-countries` Search the list of Google-supported countries by name or country code to use in Google Search API requests. ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | Filters countries based on a search string. The search is **non-case-sensitive** and returns all countries whose names contain the specified string. **Example:** fr | ## Responses ### 200 Successful response ```json { "type": "array", "items": { "type": "object", "properties": { "country_code": { "type": "string" }, "country_name": { "type": "string" } } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # Google Languages Finder **GET** `https://api.piloterr.com/v2/finder/google-languages` Search the list of Google-supported languages by name to retrieve language codes for use in Google Search API requests. ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | Filters languages based on a search string. The search is **non-case-sensitive** and returns all languages whose names contain the specified string. **Example:** french | ## Responses ### 200 Successful response ```json { "type": "array", "items": { "type": "object", "properties": { "language_code": { "type": "string" }, "language_name": { "type": "string" } } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # Google Locations Finder **GET** `https://api.piloterr.com/v2/finder/google-locations` Search Google-supported locations by name to retrieve location IDs and GPS coordinates for geo-targeted search API calls. ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | Restricts your search to locations that contain the supplied string. **Example:** Paris **Note:** Searching 'Austin' will find 'Austin, TX', 'The University of Texas at Austin', 'Rochester, MN-Mason City, IA-Austin, MN, United States', etc. | ## Responses ### 200 Successful response ```json { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "google_id": { "type": "integer" }, "google_parent_id": { "type": "integer" }, "name": { "type": "string" }, "canonical_name": { "type": "string" }, "country_code": { "type": "string" }, "target_type": { "type": "string" }, "reach": { "type": "integer" }, "gps": { "type": "array", "items": { "type": "number" } } } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # Leroy Merlin Products Finder **GET** `https://api.piloterr.com/v2/finder/leroymerlin-products` Find Leroy Merlin product URLs by product name, ID, or any combination of filters to use in product detail and rendering API calls. ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `search` | query | `string` | No | Free-text search across product titles and IDs. Optional if at least one filter is provided. **Example:** perceuse | | `query` | query | `string` | No | Legacy alias of `search`. Kept for backward compatibility. | | `id` | query | `string` | No | Filter by one or several internal product IDs. Provide a comma-separated list to match multiple IDs. **Example:** 84827484,84827521 | | `domain` | query | `string` | No | Filter by website domain. Comma-separated values are accepted. **Example:** fr | | `filter` | query | `string` | No | Raw filter expression for advanced filtering. Combined with the shorthand filters using `AND`. **Example:** domain = "fr" AND title CONTAINS "festool" | | `limit` | query | `number` | No | Maximum number of results to return. Default is 10, maximum is 100. | | `offset` | query | `number` | No | Number of results to skip for pagination. Default is 0. | | `sort` | query | `string` | No | Sort the results. Provide one or several attributes with `:asc` or `:desc`, comma-separated. **Example:** title:asc | | `fields` | query | `string` | No | Comma-separated list of fields to return. Defaults to all fields. **Example:** id,title,url | | `count` | query | `boolean` | No | When `true`, the response is wrapped in an object containing the total estimated count plus the hits: `{ count, hits }`. When `false` or omitted, returns the raw hits array. **Example:** true | ## Responses ### 200 Successful response ```json { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "title": { "type": "string" }, "domain": { "type": "string" } } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # LinkedIn Industries Finder **GET** `https://api.piloterr.com/v2/finder/linkedin-industries` Search LinkedIn industry taxonomy to retrieve industry IDs and hierarchies for use in LinkedIn API calls and data enrichment. ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | Restricts your search to industries that contain the supplied string. **Example:** software development | ## Responses ### 200 Successful response ```json { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "industry_id": { "type": "string" }, "level": { "type": "string" }, "label": { "type": "string" }, "hierarchie": { "type": "string" }, "description": { "type": "string" } } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # Fiverr Profile Info **GET** `https://api.piloterr.com/v2/fiverr/profile/info` Extract complete public profile data from any Fiverr seller, including gigs, ratings, reviews, skills, portfolio, and consultation pricing. **Credit cost:** 1 credit per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | Fiverr profile URL of the seller you want to extract information from. **Example:** https://www.fiverr.com/likaalavidze The API returns the seller's full public profile including their bio, gigs, ratings, reviews, skills, portfolio, and consultation pricing. **Note:** Only publicly visible seller profiles are supported. The username alone (e.g. `likaalavidze`) without the full URL is not accepted. | ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "address": { "type": "object", "properties": { "country_code": { "type": "string" }, "country_name": { "type": "string" } } }, "profile": { "type": "object", "properties": { "display_name": { "type": "string" } } }, "joined_at": { "type": "integer" }, "languages": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "level": { "type": "string" } } } }, "profile_image_url": { "type": "string" }, "is_activation_completed": { "type": "boolean" } } }, "is_pro": { "type": "boolean" }, "rating": { "type": "object", "properties": { "count": { "type": "integer" }, "score": { "type": "integer" } } }, "seller_level": { "type": "string" }, "achievement_level": { "type": "string" }, "one_liner_title": { "type": "string" }, "description": { "type": "string" }, "is_active": { "type": "boolean" }, "is_on_vacation": { "type": "boolean" }, "approved_gigs_count": { "type": "integer" }, "hourly_rate": { "type": "object", "properties": { "price_in_cents": { "type": "integer" } } }, "response_time": { "type": "object", "properties": { "in_hours": { "type": "integer" } } }, "gigs_data": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "gig_id": { "type": "integer" }, "is_pro": { "type": "boolean" }, "status": { "type": "string" }, "price_i": { "type": "integer" }, "seller_level": { "type": "string" }, "seller_rating": { "type": "object", "properties": { "count": { "type": "integer" }, "score": { "type": "number" } } } } } } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # Fiverr Search **GET** `https://api.piloterr.com/v2/fiverr/search` Search Fiverr gigs using a direct search URL and receive paginated listings with seller information, gig titles, images, and seller levels. **Credit cost:** 1 credit per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | A Fiverr search URL for gigs. **Example:** https://www.fiverr.com/search/gigs?query=website+development The API returns paginated gig listings including seller information, images, gig URLs, and seller levels. **Notes:** - Use a valid Fiverr gig search URL (starting with `https://www.fiverr.com/search/gigs?query=`) - You can append additional Fiverr filters to the URL (e.g. `&filter=rating`, `&delivery_time=1`) before submitting. | ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": "string" }, "title": { "type": "string" }, "images": { "type": "array", "items": { "type": "string" } }, "gig_url": { "type": "string" }, "position": { "type": "integer" }, "seller_id": { "type": "integer" }, "seller_name": { "type": "string" }, "seller_image": { "type": "string" }, "seller_level": { "type": "string" } } } }, "pagination": { "type": "object", "properties": { "next": { "type": "integer" }, "total": { "type": "integer" }, "current": { "type": "integer" }, "other_pages": { "type": "array", "items": { "type": "integer" } }, "total_pages": { "type": "integer" }, "has_next_page": { "type": "boolean" } } } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # G2 Product Info **GET** `https://api.piloterr.com/v2/g2/product/info` Retrieve comprehensive product data from G2, including ratings, reviews, pricing plans, company info, and social media metrics. **Status:** Degraded **Credit cost:** 2 credits per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | A product name or G2 product URL to look up. **Examples:** https://www.g2.com/products/postman Both the product slug and the full G2 product page URL are accepted. | | `nps_score` | query | `number` | No | Filter reviews by NPS score (1–5). - `1`: 1-star reviews only - `3`: 3-star reviews only - `5`: 5-star reviews only **Note:** By default, all reviews are returned regardless of NPS score. Use this parameter to target specific sentiment segments. | ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "rating": { "type": "number" }, "what_is": { "type": "string" }, "category": { "type": "string" }, "product_name": { "type": "string" }, "product_type": { "type": "string" }, "product_description": { "type": "string" }, "product_logo": { "type": "string" }, "seller_name": { "type": "string" }, "company_location": { "type": "string" }, "company_year_founded": { "type": "string" }, "reviews_count": { "type": "integer" }, "discussions_count": { "type": "integer" }, "twitter_url": { "type": "string" }, "twitter_followers_count": { "type": "integer" }, "linkedin_url": { "type": "string" }, "linkedin_employees_count": { "type": "integer" }, "pricing_plans": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "price": { "type": "string" } } } }, "reviews": { "type": "array", "items": { "type": "object", "properties": { "review_id": { "type": "integer" }, "review_title": { "type": "string" }, "review_rating": { "type": "integer" }, "publish_date": { "type": "string" }, "reviewer": { "type": "object", "properties": { "reviewer_industry": { "type": "string" }, "reviewer_company_size": { "type": "string" } } } } } }, "star_distribution": { "type": "object", "properties": { "1": { "type": "integer" }, "2": { "type": "integer" }, "3": { "type": "integer" }, "4": { "type": "integer" }, "5": { "type": "integer" } } } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # GitHub User Info **GET** `https://api.piloterr.com/v2/github/user/info` Retrieve public GitHub user profile data including bio, company, location, follower count, repositories, and associated email addresses. **Status:** Degraded **Credit cost:** 1 credit per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | A GitHub user identifier. Multiple formats are accepted: - **GitHub profile URL:** `https://github.com/torvalds` - **Username:** `torvalds` - **Email address:** `name@company.com` **Examples:** https://github.com/torvalds **Note:** When using an email address, the lookup resolves the associated GitHub account if one is linked publicly. | ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "array", "items": { "type": "string" } }, "login": { "type": "string" }, "company": { "type": "string" }, "location": { "type": "string" }, "ssh_keys": { "type": "string" }, "followers": { "type": "integer" }, "following": { "type": "integer" }, "avatar_url": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "public_gists": { "type": "string" }, "public_repos": { "type": "integer" } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # Glossary A reference for the terms you will encounter in the documentation, dashboard, and API responses. *** Account [#account] See [Tenant](#tenant). *** API key [#api-key] A secret string used to authenticate API requests. Each key belongs to a tenant and has an alias, category, optional quotas, and an optional expiry date. Passed via the `x-api-key` header or `x_api_key` query parameter. See [API Keys](/api-keys) for full details. *** Alias [#alias] The human-readable name of an API key, unique within a tenant. Used to identify keys in the dashboard and analytics. *** Auto Top-Up [#auto-top-up] A feature that automatically purchases a credit pack when your remaining balance drops below a configured threshold. Protected by a 72-hour cooldown between purchases. Requires an active paid subscription. See [Auto Top-Up](/auto-top-up) for full details. *** Billing period [#billing-period] The active subscription window used to measure quota consumption. Determined by the `currentPeriodStart` and `currentPeriodEnd` fields from Stripe. If no active subscription is found, the billing period defaults to the current calendar month. *** Category [#category] A label on an API key (`production`, `development`, `staging`, or custom). Used for filtering and organization in the dashboard. Does not change how the API processes the request. *** Credit [#credit] The unit of API consumption. Each billable request deducts a number of credits determined by the endpoint's cost. Credits are stored as ledger entries: a negative amount means credits were granted, a positive amount means they were consumed. See [Credits](/credits) for the cost per endpoint. *** Extra credits [#extra-credits] Credits purchased separately from a subscription (via one-time packs or Auto Top-Up). They are drawn from when the subscription quota is exhausted. Also includes onboarding grants. Distinct from the subscription quota because they do not reset at the end of a billing period. *** Per-key quota [#per-key-quota] An optional request limit set on a specific API key. Enforced on rolling time windows: all-time total, last 24 hours, last 7 days, and last 30 days. Independent of the subscription quota. *** Plan [#plan] A subscription product (e.g. "Starter", "Pro") that defines a set of features: API call quota, rate limits, access to extra credits, and more. A tenant can hold multiple active plan products simultaneously. *** Quota [#quota] The maximum number of API calls (weighted by credit cost) allowed within a billing period. Comes from the `api` feature on the active plan. When exhausted, extra credits are used if available; otherwise requests are rejected with `402`. *** Rate limit [#rate-limit] There are two separate rate-limiting systems. **Plan limits** (per second / per minute) apply to all keys on an account and are set by the subscription plan. Exceeding them returns `429 Too Many Requests`. **Per-key quotas** (total / daily / weekly / monthly rolling windows) are optional hard caps configured per key. Exceeding them returns `401 Rate Limit Exceeded`. See [API Keys](/api-keys) for details. *** Subscription [#subscription] A recurring billing arrangement linking a tenant to one or more plans. Managed through Stripe. Determines the billing period, quota, and features available to the tenant. *** Tenant [#tenant] The organizational unit in the platform, equivalent to an account or workspace. All API keys, usage, credits, and subscriptions are scoped to a tenant. Users can belong to multiple tenants. See [Account](#account). *** Threshold [#threshold] The percentage of remaining credits at which Auto Top-Up activates. Configurable between 10% and 30%. # Google Images **GET** `https://api.piloterr.com/v2/google/images` Google Images Scraper API – bringing the power of visual search to your fingertips. **Credit cost:** 1 credit per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | The image search query to execute on Google Images. **Example:** mountain landscape | | `gl` | query | `string` | No | Two-letter country code for the Google image search country context. - `us`: United States (default) - `fr`: France - `gb`: United Kingdom - `de`: Germany **Example:** us | | `hl` | query | `string` | No | Two-letter language code for the Google interface language. Controls the language context of the image search. - `en`: English (default) - `fr`: French - `de`: German - `es`: Spanish **Example:** en | | `page` | query | `number` | No | Page number for pagination. Images are returned in batches of 100 per page. - `1`: First 100 images (default) - `2`: Next 100 images - `3`: Next 100 images, etc. **Note:** To retrieve additional images, increment this parameter with the same query. | ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "images": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "link": { "type": "string" }, "title": { "type": "string" }, "domain": { "type": "string" }, "source": { "type": "string" }, "position": { "type": "integer" }, "image_width": { "type": "integer" }, "image_height": { "type": "integer" } } } }, "search_parameters": { "type": "object", "properties": { "q": { "type": "string" }, "gl": { "type": "string" }, "hl": { "type": "string" }, "page": { "type": "integer" }, "engine": { "type": "string" } } } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # Google Jobs **GET** `https://api.piloterr.com/v2/google/jobs` **Credit cost:** 1 credit per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | Job search term or keyword for querying Google job listings. | ## Responses ### 200 Successful response ```json { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "category": { "type": "string" }, "location": { "type": "string" }, "description": { "type": "string" } } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # Google News **GET** `https://api.piloterr.com/v2/google/news` Extract real-time news articles from Google News with advanced filtering by topic, location, language, and pagination. **Credit cost:** 1 credit per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | The news search query to execute on Google News. Supports standard Google search operators. **Examples:** - `artificial intelligence` — news about AI - `site:techcrunch.com startup` — news from a specific domain - `"climate change" 2024` — exact phrase search **Example:** artificial intelligence news | | `location` | query | `string` | No | City or region from which the news search should originate. Simulates a search performed from the specified location. **Examples:** - `New York, NY` - `Paris, France` - `Tokyo, Japan` | | `uule` | query | `string` | No | Google-encoded location string for precise geographic targeting. Use this instead of `location` when you need exact control. | | `gl` | query | `string` | No | Two-letter country code for the Google News country context. - `us`: United States - `fr`: France - `gb`: United Kingdom - `de`: Germany **Example:** us | | `hl` | query | `string` | No | Two-letter language code for the Google News language context. - `en`: English - `fr`: French - `de`: German - `es`: Spanish **Example:** en | | `page` | query | `number` | No | Page number of news results to retrieve. - `1`: First page (default) - `2`: Second page, etc. | | `num` | query | `number` | No | Maximum number of results to return per page. - `10`: Default - `40`: 40 results - `100`: 100 results | ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "next": { "type": "integer" }, "current": { "type": "integer" }, "other_pages": { "type": "array", "items": { "type": "integer" } }, "has_next_page": { "type": "boolean" } } }, "organic_results": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "link": { "type": "string" }, "title": { "type": "string" }, "domain": { "type": "string" }, "source": { "type": "string" }, "snippet": { "type": "string" }, "position": { "type": "integer" }, "displayed_link": { "type": "string" }, "snippet_matched": { "type": "array", "items": {} } } } }, "search_parameters": { "type": "object", "properties": { "q": { "type": "string" }, "gl": { "type": "string" }, "hl": { "type": "string" }, "num": { "type": "integer" }, "page": { "type": "integer" }, "uule": { "nullable": true }, "engine": { "type": "string" }, "location": { "nullable": true } } } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # Google Search Autocomplete **GET** `https://api.piloterr.com/v2/google/search/autocomplete` Retrieve real-time Google Search autocomplete suggestions for any query, with support for language and country localization. **Credit cost:** 1 credit per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | The partial or complete search query for which you want to retrieve autocomplete suggestions from Google. **Example:** coffee | | `cp` | query | `number` | No | Cursor position in the query string where autocomplete suggestions should be generated. Determines which part of the query is being completed. - `0`: Suggestions based on the full query (default) - `5`: Suggestions based on the first 5 characters of the query | | `gl` | query | `string` | No | Two-letter country code for the Google search country context. Defines which regional Google index is used. - `us`: United States (default) - `fr`: France - `gb`: United Kingdom - `de`: Germany **Example:** us | | `hl` | query | `string` | No | Two-letter language code for the Google interface language. Controls the language in which suggestions are returned. - `en`: English (default) - `fr`: French - `de`: German - `es`: Spanish **Example:** en | ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "suggestions": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" } } } }, "search_parameters": { "type": "object", "properties": { "q": { "type": "string" }, "cp": { "type": "integer" }, "gl": { "type": "string" }, "hl": { "type": "string" }, "engine": { "type": "string" }, "google_domain": { "type": "string" } } } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # Google Search **GET** `https://api.piloterr.com/v2/google/search` Scrape real-time Google search results with organic listings, knowledge graph, related searches, and advanced filters. **Credit cost:** 1 credit per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | The search query to execute on Google. Supports all standard Google search operators. **Examples:** - `best electric cars 2024` — standard keyword search - `site:linkedin.com Bill Gates` — restrict results to a specific domain - `intitle:"growth hacking" startup` — match the page title - `inurl:blog python tutorial` — match part of the URL **Example:** best electric cars 2024 | | `tbs` | query | `string` | No | Advanced time-range and filter string for Google Search. Used to restrict results by recency. - `qdr:h`: Last hour - `qdr:d`: Last day - `qdr:w`: Last week - `qdr:m`: Last month - `qdr:y`: Last year **Example:** qdr:w | | `location` | query | `string` | No | City or region from which the search should originate. Simulates a real user's search from the specified location. **Examples:** - `New York, NY` - `Paris, France` - `Tokyo, Japan` | | `uule` | query | `string` | No | Google-encoded location string for precise geographic targeting. | | `gl` | query | `string` | No | Two-letter country code for the Google search country context. - `us`: United States - `fr`: France - `gb`: United Kingdom - `de`: Germany **Example:** us | | `hl` | query | `string` | No | Two-letter language code for the Google interface language. - `en`: English - `fr`: French - `de`: German - `es`: Spanish **Example:** en | | `page` | query | `number` | No | Page number of search results to retrieve. - `1`: First page (default) - `2`: Second page, etc. | | `num` | query | `number` | No | Maximum number of results to return per page (e.g. `10`, `40`, `100`). **Note:** This parameter is deprecated and may not reliably affect the number of results returned. | ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "pagination": { "type": "object", "properties": { "next": { "type": "integer" }, "current": { "type": "integer" }, "other_pages": { "type": "array", "items": { "type": "integer" } }, "has_next_page": { "type": "boolean" } } }, "knowledge_graph": { "nullable": true }, "organic_results": { "type": "array", "items": { "type": "object", "properties": { "link": { "type": "string" }, "title": { "type": "string" }, "domain": { "type": "string" }, "source": { "type": "string" }, "snippet": { "type": "string" }, "position": { "type": "integer" }, "displayed_link": { "type": "string" }, "snippet_matched": { "type": "array", "items": { "type": "string" } } } } }, "related_searches": { "type": "array", "items": { "type": "object", "properties": { "query": { "type": "string" } } } }, "search_parameters": { "type": "object", "properties": { "q": { "type": "string" }, "gl": { "type": "string" }, "hl": { "type": "string" }, "tbs": { "nullable": true }, "page": { "type": "integer" }, "uule": { "nullable": true }, "engine": { "type": "string" }, "location": { "nullable": true } } }, "search_information": { "type": "object", "properties": { "total_results": { "nullable": true }, "time_taken_displayed": { "nullable": true } } } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # Google Videos **GET** `https://api.piloterr.com/v2/google/videos` Scrape video results from Google Videos search including YouTube, Reddit, and other video platforms, with location and language support. **Credit cost:** 1 credit per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | The video search query to execute on Google Videos. Supports standard Google search operators. **Examples:** - `paris travel guide` — travel videos about Paris - `machine learning tutorial` — educational ML videos - `site:youtube.com cooking beginner` — restrict to YouTube results **Example:** paris travel guide | | `location` | query | `string` | No | City or region from which the video search should originate. **Examples:** - `New York, NY` - `Paris, France` | | `uule` | query | `string` | No | Google-encoded location string for precise geographic targeting. | | `gl` | query | `string` | No | Two-letter country code for the Google video search country context. - `us`: United States - `fr`: France - `gb`: United Kingdom - `de`: Germany **Example:** us | | `hl` | query | `string` | No | Two-letter language code for the Google interface language. - `en`: English - `fr`: French - `de`: German - `es`: Spanish **Example:** en | | `page` | query | `number` | No | Page number of video results to retrieve. - `1`: First page (default) - `2`: Second page, etc. | | `num` | query | `number` | No | Maximum number of video results to return per page. - `10`: Default - `40`: 40 results - `100`: 100 results | ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "organic_results": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "link": { "type": "string" }, "title": { "type": "string" }, "domain": { "type": "string" }, "source": { "type": "string" }, "channel": { "type": "string" }, "snippet": { "type": "string" }, "duration": { "type": "string" }, "position": { "type": "integer" }, "video_id": { "type": "string" }, "displayed_link": { "type": "string" }, "snippet_matched": { "type": "array", "items": { "type": "string" } } } } }, "search_parameters": { "type": "object", "properties": { "q": { "type": "string" }, "gl": { "type": "string" }, "hl": { "type": "string" }, "num": { "type": "integer" }, "page": { "type": "integer" }, "uule": { "nullable": true }, "engine": { "type": "string" }, "location": { "nullable": true } } } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # Homestra Ad **GET** `https://api.piloterr.com/v2/homestra/ad` Retrieve detailed property listing data from Homestra, including price, size, location, features, photos, and nearby properties. **Credit cost:** 1 credit per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | A Homestra property URL or slug. **Examples:** https://homestra.com/property/charming-4-bedroom-stone-house-with-historic-towers-in-idyllic-french-village/ Both the full URL and the slug (the last part of the URL path) are accepted. | ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "id": { "type": "string" }, "city": { "type": "string" }, "size": { "type": "integer" }, "slug": { "type": "string" }, "type": { "type": "string" }, "price": { "type": "integer" }, "title": { "type": "string" }, "garden": { "type": "boolean" }, "region": { "type": "string" }, "status": { "type": "string" }, "address": { "type": "string" }, "parking": { "type": "boolean" }, "basement": { "type": "boolean" }, "location": { "type": "object", "properties": { "type": { "type": "string" }, "coordinates": { "type": "array", "items": { "type": "number" } } } }, "lot_size": { "type": "integer" }, "condition": { "type": "string" }, "furnished": { "type": "boolean" }, "created_at": { "type": "string" }, "country_code": { "type": "string" }, "swimming_pool": { "type": "boolean" }, "amount_of_bedrooms": { "type": "integer" }, "amount_of_bathrooms": { "type": "integer" }, "featured_photo_url": { "type": "string" }, "nearby_properties": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "slug": { "type": "string" }, "price": { "type": "integer" }, "title": { "type": "string" } } } } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # Homestra Search **GET** `https://api.piloterr.com/v2/homestra/search` Search Homestra property listings using a direct search URL with filters, returning structured results with prices, sizes, locations, and photos. **Credit cost:** 1 credit per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | A valid Homestra search URL with optional filters. **Example:** https://homestra.com/list/houses-for-sale/?maximum-price=900000&minimum-price=75000&page=1 You can customize filters directly in the URL, including price range, property type, location, and page number. **Notes:** - URL-encode `&` as `%26` when passing the query in a GET request parameter. - Use `page=N` to paginate through results. | ## Responses ### 200 Successful response ```json { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "city": { "type": "string" }, "size": { "type": "integer" }, "slug": { "type": "string" }, "type": { "type": "string" }, "price": { "type": "integer" }, "title": { "type": "string" }, "status": { "type": "string" }, "address": { "type": "string" }, "location": { "type": "object", "properties": { "type": { "type": "string" }, "coordinates": { "type": "array", "items": { "type": "number" } } } }, "lot_size": { "type": "integer" }, "photo_url": { "type": "string" }, "country_code": { "type": "string" }, "listing_date": { "type": "string" } } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # Indeed Company Info **GET** `https://api.piloterr.com/v2/indeed/company/info` Retrieve comprehensive company data from Indeed, including founding year, revenue, employee count, industry, and employee reviews. **Credit cost:** 2 credits per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | A company identifier to look up on Indeed. Multiple formats are accepted: - **Indeed company URL:** `https://indeed.com/cmp/Microsoft` - **Company name:** `Microsoft` **Examples:** https://indeed.com/cmp/Apple **Note:** Using the full Indeed URL is preferred for more accurate results when multiple companies share a similar name. | ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "founded": { "type": "integer" }, "revenue": { "type": "string" }, "website": { "type": "string" }, "industry": { "type": "string" }, "logo_url": { "type": "string" }, "company_url": { "type": "string" }, "description": { "type": "string" }, "headquarter": { "type": "string" }, "staff_range": { "type": "string" }, "company_name": { "type": "string" }, "dynamic_sections": { "type": "object", "properties": { "faq": { "type": "object", "properties": { "faqs": { "type": "array", "items": { "type": "object", "properties": { "answer_text": { "type": "string" }, "answer_links": { "type": "array", "items": {} }, "question_text": { "type": "string" } } } } } } } } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # Introduction Get started with the Piloterr API in minutes. Make HTTP requests to our endpoints and receive structured JSON responses. Quick Start [#quick-start] Get your API key [#get-your-api-key] Sign up on your [dashboard](https://app.piloterr.com) and copy your API key from the **Settings** page. Make your first request [#make-your-first-request] Include your key in the `x-api-key` header and call any endpoint: ```bash curl "https://api.piloterr.com/v2/usage" \ -H "x-api-key: YOUR_API_KEY" ``` Handle the response [#handle-the-response] Every successful request returns a JSON object with structured data. See individual endpoint pages for response schemas and examples. Authentication [#authentication] All API requests must include an `x-api-key` header. You can find your key in your [dashboard → API Keys](https://app.piloterr.com/). ```bash curl -H "x-api-key: xxxx" https://api.piloterr.com/v2/usage ``` Keep your API key secret. Do not expose it in client-side code or public repositories. Status Codes [#status-codes] Billing applies to successful requests: `200` for synchronous calls, `201` for asynchronous jobs. `404` billing varies by endpoint (check each endpoint page). All other 4xx/5xx responses are free. | Code | Billed | Status | Action | | ----- | ------ | ------------------- | -------------------------------------------------------------------------------------------------------- | | `200` | Yes | Successful API Call | No action required. | | `201` | Yes | Job Created | No action required. | | `202` | No | Accepted (Async) | The request was accepted and is being processed. Use the job ID to check the status. | | `400` | No | Bad Request | Verify your parameters and their types. Check the documentation for more information. | | `401` | No | Invalid API Key | Check your API key (`x-api-key` header or `x_api_key` query string). | | `401` | No | Inactive API Key | Activate your API key in the API Keys section of your account settings. | | `401` | No | Expired API Key | Update your API key or generate a new one. | | `401` | No | Rate Limit Exceeded | Consider upgrading your current plan or contact our sales team. | | `402` | No | Payment Required | Settle any outstanding invoices to continue using the API. | | `403` | No | Forbidden | Verify your permissions. Contact us if you believe this is a mistake. | | `404` | Varies | Not Found | Billing is endpoint-specific. Check the individual endpoint documentation. | | `413` | No | Payload Too Large | The uploaded file or request body exceeds the size limit. Check the API documentation for maximum sizes. | | `500` | No | Internal Error | Retry the action or contact our support team. | See the [Credits](/credits) page for a full breakdown per endpoint, [API Keys](/api-keys) for key management, and [Best Practices](/best-practices) and [Error Handling](/error-handling) for integration guidance. New to the platform? The [Glossary](/glossary) defines all key terms. Endpoints [#endpoints] Browse all available endpoints in the sidebar, or jump directly: # Instagram Post Info **GET** `https://api.piloterr.com/v2/instagram/post/info` Monitor competitors and market trends by scraping Instagram posts for valuable data. **Credit cost:** 1 credit per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | The Instagram post or reel to retrieve. Accepts a full URL or a shortcode. **Accepted formats:** - `https://www.instagram.com/p/CshTQQlMGMl` — full post URL - `CshTQQlMGMl` — post shortcode only **Example:** https://www.instagram.com/p/CshTQQlMGMl **Notes:** - **Private accounts:** Posts from private accounts cannot be retrieved. - **Deleted posts:** Returns a not-found error if the post no longer exists. | ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "id": { "type": "string" }, "text": { "type": "string" }, "is_video": { "type": "boolean" }, "owner_id": { "type": "string" }, "sponsors": { "type": "array", "items": {} }, "shortcode": { "type": "string" }, "text_lang": { "type": "string" }, "text_tags": { "type": "array", "items": {} }, "timestamp": { "type": "integer" }, "like_count": { "type": "integer" }, "location_id": { "type": "string" }, "created_time": { "type": "string" }, "product_type": { "nullable": true }, "location_name": { "type": "string" }, "location_slug": { "type": "string" }, "related_posts": { "nullable": true }, "comments_count": { "type": "integer" }, "paid_partnership": { "type": "boolean" }, "text_tagged_users": { "type": "array", "items": {} }, "video_plays_count": { "nullable": true }, "video_views_count": { "nullable": true }, "is_comments_disabled": { "type": "boolean" }, "attached_media_display_url": { "type": "string" }, "attached_media_tagged_users": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "username": { "type": "string" } } } }, "attached_carousel_media_urls": { "type": "array", "items": { "type": "string" } } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # Instagram User Info **GET** `https://api.piloterr.com/v2/instagram/user/info` Gather user insights efficiently from Instagram for targeted marketing strategies. **Credit cost:** 1 credit per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | The Instagram user to look up. Accepts a full profile URL or a username. **Accepted formats:** - `https://www.instagram.com/k.mbappe` — full profile URL - `k.mbappe` — username only **Example:** https://www.instagram.com/k.mbappe **Notes:** - **Private accounts:** Profile data is returned but posts array will be empty. - **Deactivated accounts:** Returns a not-found error. | ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "posts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "likes": { "type": "integer" }, "caption": { "type": "string" }, "comments": { "type": "integer" }, "is_video": { "type": "boolean" }, "shortcode": { "type": "string" }, "timestamp": { "type": "integer" }, "display_url": { "type": "string" } } } }, "avatar": { "type": "string" }, "gender": { "type": "string" }, "private": { "type": "boolean" }, "website": { "nullable": true }, "username": { "type": "string" }, "verified": { "type": "boolean" }, "followers": { "type": "integer" }, "following": { "type": "integer" }, "description": { "type": "string" }, "category_name": { "type": "string" }, "business_account": { "type": "boolean" }, "business_category_name": { "type": "string" } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # Kick User Info **GET** `https://api.piloterr.com/v2/kick/user/info` Retrieve complete public channel data from Kick including streamer profile, follower count, live status, and recent categories. **Credit cost:** 1 credit per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | The Kick channel to look up. Accepts a full channel URL or a username/slug. **Accepted formats:** - `https://kick.com/xqc` — full channel URL - `xqc` — channel slug/username only **Example:** https://kick.com/xqc **Notes:** - **Banned channels:** The `is_banned` field will be `true` for banned users but data may still be returned. - **Offline streamers:** The `livestream` field will be `null` when the channel is not live. | ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "id": { "type": "integer" }, "role": { "nullable": true }, "slug": { "type": "string" }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "bio": { "type": "string" }, "city": { "nullable": true }, "gender": { "nullable": true }, "discord": { "type": "string" }, "twitter": { "type": "string" }, "youtube": { "type": "string" }, "username": { "type": "string" }, "instagram": { "type": "string" }, "profile_pic": { "type": "string" } } }, "muted": { "type": "boolean" }, "user_id": { "type": "integer" }, "verified": { "type": "boolean" }, "is_banned": { "type": "boolean" }, "livestream": { "nullable": true }, "vod_enabled": { "type": "boolean" }, "banner_image": { "type": "object", "properties": { "url": { "type": "string" } } }, "playback_url": { "type": "string" }, "follower_badges": { "type": "array", "items": {} }, "followers_count": { "type": "integer" }, "subscription_enabled": { "type": "boolean" }, "recent_categories": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "slug": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } } } } } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # Leboncoin Ad **GET** `https://api.piloterr.com/v2/leboncoin/ad` Extract full details from a Leboncoin ad including price, location, attributes, seller info, and images. **Credit cost:** 1 credit per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | Leboncoin ad ID or full ad URL. **Accepted formats:** - Ad ID: `2715494476` - Full URL: `https://www.leboncoin.fr/voitures/2715494476.htm` **Example:** https://www.leboncoin.fr/voitures/2715494476.htm **Note:** The ad must be currently active on Leboncoin. Expired or deleted ads return an error. | | `return_page_source` | query | `boolean` | No | Set to `true` to include the full raw HTML source of the ad page in the response. **Use case:** Useful for advanced data extraction or debugging when the structured response does not include all desired fields. | ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "list_id": { "type": "integer" }, "category": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" } } }, "subject": { "type": "string" }, "body": { "type": "string" }, "price": { "type": "array", "items": { "type": "integer" } }, "price_cents": { "type": "array", "items": { "type": "integer" } }, "owner": { "type": "object", "properties": { "type": { "type": "string" }, "name": { "type": "string" }, "user_id": { "type": "string" }, "siren": { "nullable": true } } }, "location": { "type": "object", "properties": { "city": { "type": "string" }, "zipcode": { "type": "string" }, "department_id": { "type": "string" }, "department_name": { "type": "string" }, "region_id": { "type": "string" }, "region_name": { "type": "string" }, "lat": { "type": "number" }, "lng": { "type": "number" } } }, "attributes": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "value": { "type": "string" }, "value_label": { "type": "string" } } } }, "images": { "type": "object", "properties": { "urls": { "type": "array", "items": { "type": "string" } } } }, "creation_date": { "type": "string" }, "expiration_date": { "type": "string" }, "status": { "type": "string" }, "url": { "type": "string" } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # Leboncoin Search API **POST** `https://api.piloterr.com/v2/leboncoin/search_api` Search Leboncoin listings via structured POST API with advanced filters for category, location, price range, seller type, and sorting. **Credit cost:** 1 credit per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "total": { "type": "integer" }, "total_all": { "type": "integer" }, "total_pro": { "type": "integer" }, "total_private": { "type": "integer" }, "max_pages": { "type": "integer" }, "ads": { "type": "array", "items": { "type": "object", "properties": { "list_id": { "type": "integer" }, "ad_type": { "type": "string" }, "url": { "type": "string" }, "category_id": { "type": "string" }, "category_name": { "type": "string" }, "subject": { "type": "string" }, "body": { "type": "string" }, "brand_name": { "nullable": true }, "price": { "type": "array", "items": { "type": "integer" } }, "price_cents": { "type": "array", "items": { "type": "integer" } }, "currency": { "type": "string" }, "owner": { "type": "object", "properties": { "type": { "type": "string" }, "name": { "type": "string" }, "siren": { "nullable": true } } }, "location": { "type": "object", "properties": { "country_id": { "type": "string" }, "city": { "type": "string" }, "zipcode": { "type": "string" }, "department_id": { "type": "string" }, "department_name": { "type": "string" }, "region_id": { "type": "string" }, "region_name": { "type": "string" }, "lat": { "type": "number" }, "lng": { "type": "number" } } }, "attributes": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "value": { "type": "string" }, "value_label": { "type": "string" } } } }, "images": { "type": "object", "properties": { "urls": { "type": "array", "items": { "type": "string" } }, "small_url": { "type": "string" }, "thumb_url": { "type": "string" }, "nb_images": { "type": "integer" } } }, "status": { "type": "string" }, "creation_date": { "type": "string" }, "expiration_date": { "type": "string" } } } } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # Leboncoin Search **GET** `https://api.piloterr.com/v2/leboncoin/search` Scrape Leboncoin search results or category pages by URL, returning paginated listings with price, location, and attributes. **Credit cost:** 1 credit per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | Full Leboncoin search or category URL. Both keyword searches and category browse URLs are supported. **Supported URL types:** - Category with filters: `https://www.leboncoin.fr/voitures/offres/ile_de_france/` - Keyword search: `https://www.leboncoin.fr/recherche?text=iphone+15&category=38` **Examples:** https://www.leboncoin.fr/voitures/offres/ile_de_france/ https://www.leboncoin.fr/recherche?text=macbook&category=15 **Note:** Pagination can be added by appending `&page=2` to the URL. | ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "total": { "type": "integer" }, "ads": { "type": "array", "items": { "type": "object", "properties": { "list_id": { "type": "integer" }, "category_id": { "type": "string" }, "category_name": { "type": "string" }, "subject": { "type": "string" }, "body": { "type": "string" }, "price": { "type": "array", "items": { "type": "integer" } }, "owner": { "type": "object", "properties": { "type": { "type": "string" }, "name": { "type": "string" } } }, "location": { "type": "object", "properties": { "city": { "type": "string" }, "zipcode": { "type": "string" }, "department_name": { "type": "string" }, "region_name": { "type": "string" } } }, "attributes": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "value": { "type": "string" }, "value_label": { "type": "string" } } } }, "images": { "type": "object", "properties": { "small_url": { "type": "string" }, "nb_images": { "type": "integer" } } }, "url": { "type": "string" }, "status": { "type": "string" }, "creation_date": { "type": "string" } } } }, "pagination": { "type": "object", "properties": { "page": { "type": "integer" }, "total_pages": { "type": "integer" } } } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # LinkedIn Company Info **GET** `https://api.piloterr.com/v2/linkedin/company/info` Access critical business insights with our LinkedIn Company Scraper API for strategic analysis. **Credit cost:** 1 credit per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | No | The target LinkedIn company to look up. Accepts a username, full URL, or numeric company ID. **Accepted formats:** - `ferrari` — LinkedIn username/slug - `https://it.linkedin.com/company/ferrari` — full LinkedIn company URL - `7050` — numeric LinkedIn company ID **Example:** https://www.linkedin.com/company/ferrari | | `domain` | query | `string` | No | A domain name to perform a **reverse website lookup** and find the matching LinkedIn company. **Accepted formats:** - `guideflow.com` — bare domain - `https://www.guideflow.com` — full URL (domain is extracted automatically) **Example:** guideflow.com | ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "posts": { "type": "array", "items": { "type": "object", "properties": { "post_id": { "type": "string" }, "post_url": { "type": "string" } } } }, "founded": { "type": "integer" }, "tagline": { "type": "string" }, "website": { "type": "string" }, "industry": { "type": "string" }, "logo_url": { "type": "string" }, "employees": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "profile_url": { "type": "string" } } } }, "locations": { "type": "array", "items": { "type": "string" } }, "company_id": { "type": "integer" }, "company_url": { "type": "string" }, "description": { "type": "string" }, "headquarter": { "type": "object", "properties": { "city": { "type": "string" }, "line1": { "type": "string" }, "country": { "type": "string" }, "postal_code": { "type": "string" } } }, "staff_count": { "type": "integer" }, "staff_range": { "type": "string" }, "company_name": { "type": "string" }, "specialities": { "type": "array", "items": { "type": "string" } }, "follower_count": { "type": "integer" } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # LinkedIn Job Count **GET** `https://api.piloterr.com/v2/linkedin/job/count` Obtain real-time job counts on LinkedIn by industry, region, and role for strategic planning. **Credit cost:** 1 credit per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `keyword` | query | `string` | No | Job title or keyword to count matching postings. **Example:** Software Engineer Leave empty to count all jobs matching the other filters. | | `experience_level` | query | `string` | No | Filter by seniority level. **Accepted values:** - `internship`: Internship positions - `entry_level`: Entry-level roles - `associate`: Associate-level roles - `mid_senior`: Mid to senior-level roles - `director`: Director-level and above | | `job_type` | query | `string` | No | Filter by employment type. **Accepted values:** - `full_time`: Full-time positions - `part_time`: Part-time positions - `contract`: Contract roles - `temporary`: Temporary roles - `internship`: Internships - `volunteer`: Volunteer positions | | `when` | query | `string` | No | Filter by posting recency. **Accepted values:** - `day`: Posted in the last 24 hours - `week`: Posted in the last 7 days - `month`: Posted in the last 30 days | | `flexibility` | query | `string` | No | Filter by work arrangement. **Accepted values:** - `remote`: Fully remote positions - `flexible`: Hybrid or flexible arrangements - `on_site`: On-site only positions | | `distance` | query | `number` | No | Maximum distance radius (in miles) from the target location (requires `geo_id`). **Accepted values:** `5`, `10`, `25`, `50`, `100` | | `geo_id` | query | `string` | No | LinkedIn geo ID of the target location. **Example values:** - `92000000` — Worldwide (default) - `105073465` — France - `103644278` — United States Use the LinkedIn Job Suggest endpoint with `location=true` to find geo IDs for any location. | | `company_id` | query | `string` | No | LinkedIn numeric company ID to restrict the count to jobs posted by a specific company. **Example:** - `33246798` — TikTok Use the LinkedIn Company Info endpoint to retrieve a company's ID. | ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "count": { "type": "integer" } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # LinkedIn Job Info **GET** `https://api.piloterr.com/v2/linkedin/job/info` Dive into LinkedIn job data and trends for in-depth labor market insights. **Credit cost:** 1 credit per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | The LinkedIn job posting to retrieve. Accepts a numeric job ID or a full job posting URL. **Accepted formats:** - `4390885746` — LinkedIn numeric job ID - `https://www.linkedin.com/jobs/view/4390885746` — full job URL **Example:** https://www.linkedin.com/jobs/view/4390885746 **Notes:** - **Expired listings:** Jobs that have been closed or removed will return a not-found error. - **Private jobs:** Some employer-direct postings may be restricted. | ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "address": { "type": "object", "properties": { "city": { "type": "string" }, "state": { "type": "string" }, "county": { "nullable": true }, "country": { "type": "string" }, "country_code": { "type": "string" } } }, "job_url": { "type": "string" }, "industry": { "type": "array", "items": { "type": "string" } }, "location": { "type": "string" }, "functions": { "type": "array", "items": { "type": "string" } }, "list_date": { "type": "string" }, "recruiter": { "type": "object", "properties": { "full_name": { "type": "string" }, "headline": { "type": "string" }, "profile_url": { "type": "string" } } }, "company_url": { "type": "string" }, "company_logo": { "type": "string" }, "company_name": { "type": "string" }, "employment_type": { "type": "string" }, "job_description": { "type": "string" }, "seniority_level": { "type": "string" }, "total_applicants": { "type": "integer" }, "compensation_salary": { "type": "string" } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # LinkedIn Job Search **GET** `https://api.piloterr.com/v2/linkedin/job/search` Experience advanced job data extraction from LinkedIn, enhancing your recruitment strategy. **Credit cost:** 1 credit per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `keyword` | query | `string` | No | Job title or keyword to search for. **Example:** Software Engineer Leave empty to return all jobs matching the other filters. | | `experience_level` | query | `string` | No | Filter by seniority level. **Accepted values:** - `internship`: Internship positions - `entry_level`: Entry-level roles - `associate`: Associate-level roles - `mid_senior`: Mid to senior-level roles - `director`: Director-level and above | | `job_type` | query | `string` | No | Filter by employment type. **Accepted values:** - `full_time`: Full-time positions - `part_time`: Part-time positions - `contract`: Contract roles - `temporary`: Temporary roles - `internship`: Internships - `volunteer`: Volunteer positions | | `when` | query | `string` | No | Filter by posting date recency. **Accepted values:** - `day`: Posted in the last 24 hours - `week`: Posted in the last 7 days - `month`: Posted in the last 30 days | | `flexibility` | query | `string` | No | Filter by work arrangement. **Accepted values:** - `remote`: Fully remote positions - `flexible`: Hybrid or flexible arrangements - `on_site`: On-site only positions | | `distance` | query | `number` | No | Maximum radius in miles from the target location (requires `geo_id`). **Accepted values:** `5`, `10`, `25`, `50`, `100` | | `geo_id` | query | `string` | No | LinkedIn geo ID for the target location. Default is `92000000` (worldwide). **Example values:** - `92000000` — Worldwide - `105073465` — France - `103644278` — United States Use the LinkedIn Job Suggest endpoint with `location=true` to find geo IDs for any location. | | `company_id` | query | `string` | No | LinkedIn numeric company ID to filter results to jobs posted by a specific company. **Example:** - `33246798` — TikTok Use the LinkedIn Company Info endpoint to retrieve a company's ID. | | `page` | query | `number` | No | Page number for paginating through results. Default is `1`. Each page returns up to 25 job listings. | ## Responses ### 200 Successful response ```json { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "url": { "type": "string" }, "title": { "type": "string" }, "location": { "type": "string" }, "list_date": { "type": "string" }, "company_url": { "type": "string" }, "company_name": { "type": "string" } } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # LinkedIn Job Suggest **GET** `https://api.piloterr.com/v2/linkedin/job/suggest` Get personalized job suggestions based on keywords or locations to streamline your job search. **Credit cost:** 1 credit per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | The keyword prefix to search for job title suggestions or location names. **Example — keyword suggestions:** Air **Example — location suggestions (when `location=true`):** Par **Notes:** - Short prefixes (2–4 characters) generally yield more results. - When `location=false`, returns job-related keyword suggestions (titles, companies, schools). - When `location=true`, returns geo locations with their `geo_id` values. | | `location` | query | `boolean` | No | Set to `true` to receive location (geo) suggestions instead of keyword suggestions. **Accepted values:** - `false` (default): Returns job keyword suggestions (titles, companies, schools) - `true`: Returns geographic locations with their `geo_id` for use in Job Count and Job Search filters **Note:** The returned `geo_id` values can be used directly in the `geo_id` parameter of the LinkedIn Job Search and Job Count endpoints. | ## Responses ### 200 Successful response ```json { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" } } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # LinkedIn Post Info **GET** `https://api.piloterr.com/v2/linkedin/post/info` Simplify LinkedIn post retrieval with our efficient API for enhanced content analysis. **Credit cost:** 1 credit per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | The LinkedIn post to retrieve. Accepts a numeric post ID or a full post URL. **Accepted formats:** - `7027826235833520128` — LinkedIn numeric post ID - `https://www.linkedin.com/posts/tanyalindsay_...-activity-7027826235833520128-m0GW` — full post URL **Example:** https://www.linkedin.com/posts/tanyalindsay_we-have-been-building-a-web3-gaming-platform-activity-7027826235833520128-m0GW **Notes:** - **Deleted posts:** Returns a not-found error if the post has been removed. - **Comments:** Up to the first batch of comments are returned. Deep comment threads may be truncated. | ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "text": { "type": "string" }, "author": { "type": "object", "properties": { "url": { "type": "string" }, "full_name": { "type": "string" }, "image_url": { "nullable": true }, "profile_type": { "type": "string" } } }, "comments": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string" }, "author": { "type": "object", "properties": { "url": { "type": "string" }, "headline": { "type": "string" }, "full_name": { "type": "string" }, "image_url": { "nullable": true }, "profile_type": { "type": "string" } } } } } }, "hashtags": { "type": "array", "items": {} }, "image_url": { "type": "string" }, "images": { "type": "array", "items": { "type": "string" } }, "like_count": { "type": "integer" }, "shared_post": { "type": "object", "properties": { "id": { "type": "string" }, "link": { "nullable": true }, "text": { "type": "string" }, "image": { "nullable": true }, "title": { "nullable": true } } }, "shared_video": { "nullable": true }, "shared_link": { "nullable": true }, "comments_count": { "type": "integer" }, "date_published": { "type": "string" }, "total_engagement": { "type": "integer" }, "mentioned_profiles": { "type": "array", "items": {} } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # LinkedIn Product Info **GET** `https://api.piloterr.com/v2/linkedin/product/info` Gain competitive insights with detailed LinkedIn product information for strategic advantage. **Credit cost:** 1 credit per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | The full LinkedIn product page URL to retrieve. **Accepted format:** - `https://www.linkedin.com/products/15five` — LinkedIn product URL **Example:** https://www.linkedin.com/products/15five **Notes:** - Only LinkedIn product pages are supported (URLs starting with `https://www.linkedin.com/products/`). - Company pages and showcase pages are not supported by this endpoint — use LinkedIn Company Info instead. | ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "roles": { "type": "array", "items": { "type": "string" } }, "logo_url": { "type": "string" }, "learn_more": { "type": "string" }, "company_url": { "type": "string" }, "description": { "type": "string" }, "company_name": { "type": "string" }, "product_title": { "type": "string" }, "background_url": { "type": "string" }, "product_category": { "type": "string" }, "similar_products": { "type": "array", "items": { "type": "object", "properties": { "product_url": { "type": "string" }, "company_logo": { "type": "string" }, "product_name": { "type": "string" } } } }, "featured_customers": { "type": "array", "items": { "type": "object", "properties": { "company_url": { "type": "string" }, "company_logo": { "type": "string" }, "company_name": { "type": "string" } } } }, "product_category_url": { "type": "string" } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # LinkedIn Profile Info **GET** `https://api.piloterr.com/v2/linkedin/profile/info` Streamline recruitment and business development by extracting valuable LinkedIn profile insights. **Credit cost:** 1 credit per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | The LinkedIn profile to retrieve. Accepts a username, full profile URL, or numeric member ID. **Accepted formats:** - `williamhgates` — LinkedIn username/public identifier - `https://www.linkedin.com/in/williamhgates` — full profile URL - `ACoAAA8BYqEBmLJMezmvqCLszS5NiJtJz7L9N9M` — encoded member ID **Example:** https://www.linkedin.com/in/williamhgates **Notes:** - **Private profiles:** Some fields may be empty if the profile visibility is restricted. - **Deleted accounts:** Returns a not-found error if the account no longer exists. | ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "address": { "nullable": true }, "summary": { "type": "string" }, "headline": { "type": "string" }, "username": { "type": "string" }, "full_name": { "type": "string" }, "languages": { "type": "array", "items": {} }, "photo_url": { "type": "string" }, "profile_url": { "type": "string" }, "follower_count": { "type": "integer" }, "connection_count": { "type": "integer" }, "articles": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "title": { "type": "string" }, "author": { "type": "string" } } } }, "experiences": { "type": "array", "items": { "type": "object", "properties": { "end_date": { "nullable": true }, "company": { "type": "string" }, "job_title": { "type": "string" }, "start_date": { "type": "string" }, "company_url": { "type": "string" }, "description": { "nullable": true }, "company_logo": { "type": "string" } } } }, "educations": { "type": "array", "items": { "type": "object", "properties": { "school": { "type": "string" }, "end_date": { "nullable": true }, "end_year": { "nullable": true }, "start_date": { "nullable": true }, "start_year": { "nullable": true }, "field_of_study": { "type": "string" } } } }, "skills": { "type": "array", "items": { "type": "string" } }, "certifications": { "type": "array", "items": {} }, "recommendations": { "type": "array", "items": {} }, "member_identifier": { "type": "string" } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # ManoMano Product Offer **GET** `https://api.piloterr.com/v2/manomano/product/offer` Get all marketplace seller offers for a ManoMano product by product ID, including pricing, shipping, and seller information. **Credit cost:** 1 credit per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | ManoMano product ID. This is the numeric `product_id` returned by the ManoMano Product endpoint. **How to get this value:** 1. Call the ManoMano Product endpoint with a product URL. 2. Extract the `product_id` field from the response. 3. Use that value as the `query` parameter here. **Example:** 28910102 **Note:** Do not pass a product URL here — only numeric product IDs are accepted. | | `region` | query | `string` | Yes | Region code for the ManoMano platform. Must match the original product's domain. - `FR`: France (manomano.fr) - `GB`: United Kingdom (manomano.co.uk) - `DE`: Germany (manomano.de) - `ES`: Spain (manomano.es) - `IT`: Italy (manomano.it) **Example:** FR | ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "count": { "type": "integer" }, "results": { "type": "array", "items": { "type": "object", "properties": { "sku": { "type": "object", "properties": { "title": { "type": "string" }, "master_product": { "type": "object", "properties": { "slug": { "type": "string" }, "article_id": { "type": "string" } } } } }, "market": { "type": "string" }, "seller": { "type": "object", "properties": { "is_m_f": { "type": "boolean" }, "contract_id": { "type": "string" }, "contract_name": { "type": "string" }, "country_location": { "type": "string" } } }, "pricing": { "type": "object", "properties": { "sell_price": { "type": "object", "properties": { "amount_vat_excluded": { "type": "number" }, "amount_vat_included": { "type": "number" } } }, "retail_price": { "nullable": true }, "eco_participation": { "type": "object", "properties": { "amount_vat_included": { "type": "number" } } } } }, "packaging": { "type": "object", "properties": { "increment": { "type": "string" }, "minimum_quantity": { "type": "string" } } }, "product_id": { "type": "string" }, "is_sellable": { "type": "boolean" }, "delivery_offers": { "type": "array", "items": { "type": "object", "properties": { "estimate_delivery": { "type": "object", "properties": { "is_express": { "type": "boolean" }, "delivery_time": { "type": "object", "properties": { "max": { "type": "integer" }, "min": { "type": "integer" } } }, "free_delivery": { "type": "object", "properties": { "threshold": { "nullable": true }, "is_reached": { "type": "boolean" } } } } }, "delivery_countries": { "type": "array", "items": { "type": "string" } } } } } } } } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # ManoMano Product **GET** `https://api.piloterr.com/v2/manomano/product` Extract full product details from a ManoMano product page, including price, seller, brand, images, variants, and stock. **Credit cost:** 1 credit per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | Full ManoMano product page URL. Optionally include the `model_id` query parameter to target a specific variant. **Example:** https://www.manomano.fr/p/pergola-retractable-298l-x-213l-x-222h-m-structure-metal-epoxy-anticorrosion-toile-polyester-haute-densite-180-g-m-incluse-gris-17786586?model_id=17784588 **Notes:** - Supported domains: `manomano.fr`, `manomano.co.uk`, `manomano.de`, `manomano.es`, `manomano.it` - If `model_id` is omitted, the default variant is returned. | ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "ean": { "type": "string" }, "brand": { "type": "object", "properties": { "id": { "type": "integer" }, "url": { "type": "string" }, "name": { "type": "string" } } }, "mm_id": { "type": "integer" }, "price": { "type": "object", "properties": { "primary_price": { "type": "object", "properties": { "amount_with_vat": { "type": "number" }, "measurement_unit": { "type": "string" }, "amount_without_vat": { "type": "number" } } }, "discount_percentage": { "type": "integer" }, "eco_participation_with_vat": { "type": "number" } } }, "stock": { "type": "object", "properties": { "minimum_value": { "type": "integer" }, "increase_quantity": { "type": "integer" } } }, "title": { "type": "string" }, "seller": { "type": "object", "properties": { "id": { "type": "integer" }, "url": { "type": "string" }, "name": { "type": "string" }, "country": { "type": "string" } } }, "currency": { "type": "string" }, "delivery": { "type": "object", "properties": { "weight": { "type": "integer" }, "fulfillment": { "type": "boolean" } } }, "model_id": { "type": "integer" }, "offer_id": { "type": "string" }, "quantity": { "type": "object", "properties": { "stock": { "nullable": true }, "value": { "type": "integer" } } }, "media": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "large_url": { "type": "string" }, "regular_url": { "type": "string" }, "thumbnail_url": { "type": "string" } } } }, "variants": { "type": "object", "properties": { "list": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "values": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "label": { "type": "string" }, "value": { "type": "string" }, "model_id": { "type": "integer" }, "is_available": { "type": "boolean" } } } } } } } } } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # ManoMano Search **GET** `https://api.piloterr.com/v2/manomano/search` Search for products on ManoMano by category or keyword URL, returning listings with prices, ratings, and seller information. **Credit cost:** 1 credit per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | Full ManoMano search or category page URL. **Example:** https://www.manomano.fr/perceuse-1146 **Notes:** - Use any valid ManoMano search or category URL from any supported domain (`manomano.fr`, `manomano.co.uk`, `manomano.de`, `manomano.es`, `manomano.it`) - Pagination and filter parameters present in the URL are respected | ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "title": { "type": "string" }, "bulk": { "type": "boolean" }, "is_b2b": { "type": "boolean" }, "is_mmf": { "type": "boolean" }, "prices": { "type": "object", "properties": { "main": { "type": "number" }, "unit": { "nullable": true }, "retail": { "type": "number" }, "discount": { "type": "string" }, "secondary": { "nullable": true } } }, "rating": { "type": "number" }, "brand_id": { "type": "integer" }, "model_id": { "type": "integer" }, "offer_id": { "type": "string" }, "position": { "type": "integer" }, "article_id": { "type": "integer" }, "is_local": { "type": "boolean" }, "seller_id": { "type": "integer" }, "cpc": { "type": "number" } } } } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # Mascus Ad **GET** `https://api.piloterr.com/v2/mascus/ad` Extract full details from a Mascus heavy equipment listing including machine specs, price, seller info, images, and description. **Credit cost:** 1 credit per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | Full Mascus heavy equipment ad URL. **Supported domains:** `.com`, `.fr`, `.de`, `.es`, `.it`, `.pl`, `.nl`, `.be`, `.se`, `.fi`, `.no`, `.dk`, `.pt`, `.cz`, `.hu`, `.ro`, `.bg`, `.hr`, `.sk`, `.si`, `.lt`, `.lv`, `.ee`, `.ru`, `.ua`, `.tr`, `.za`, `.au`, `.nz`, `.ca`, `.mx`, `.br`, `.ar`, `.in`, `.cn`, `.jp`, `.kr`, `.th`, `.sg`, `.my`, `.id`, `.ph` **Example:** https://www.mascus.fr/engins-de-construction/pelles-sur-chenilles/caterpillar-320d/xeugf2of.html **Note:** The URL must point to a specific equipment listing page. The alphanumeric code at the end of the URL (e.g. `xeugf2of`) is the unique listing identifier. | ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "category": { "type": "string" }, "price": { "type": "object", "properties": { "amount": { "type": "integer" }, "currency": { "type": "string" }, "formatted": { "type": "string" }, "negotiable": { "type": "boolean" } } }, "machine": { "type": "object", "properties": { "brand": { "type": "string" }, "model": { "type": "string" }, "year": { "type": "integer" }, "hours": { "type": "integer" }, "condition": { "type": "string" }, "serial_number": { "type": "string" }, "weight_kg": { "type": "integer" }, "engine": { "type": "object", "properties": { "brand": { "type": "string" }, "power_kw": { "type": "integer" }, "power_hp": { "type": "integer" } } }, "country_of_origin": { "type": "string" } } }, "seller": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "country": { "type": "string" }, "location": { "type": "object", "properties": { "city": { "type": "string" }, "country": { "type": "string" } } }, "phone": { "type": "string" } } }, "images": { "type": "array", "items": { "type": "string" } }, "description": { "type": "string" }, "equipment": { "type": "array", "items": { "type": "string" } }, "url": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # Mascus Search **GET** `https://api.piloterr.com/v2/mascus/search` Search for heavy equipment listings on Mascus by category or search URL, returning paginated results with machine specs, pricing, and seller info. **Credit cost:** 1 credit per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | Full Mascus search or category browse URL for heavy equipment. **Supported domains:** `.com`, `.fr`, `.de`, `.es`, `.it`, `.pl`, `.nl`, `.be`, `.se`, `.fi`, `.no`, `.dk`, `.pt` and all other Mascus country domains. **Example (category browse):** https://www.mascus.fr/engins-de-construction/pelles-sur-chenilles **Example (with keyword filter):** https://www.mascus.com/construction/crawler-excavators?q=caterpillar+320 **Note:** Pagination can be added by appending `?page=2` to the URL. All equipment categories are supported (construction, agriculture, trucks, forklifts, cranes, etc.). | ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "total": { "type": "integer" }, "page": { "type": "integer" }, "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" }, "category": { "type": "string" }, "price": { "type": "object", "properties": { "amount": { "type": "integer" }, "currency": { "type": "string" }, "formatted": { "type": "string" } } }, "machine": { "type": "object", "properties": { "brand": { "type": "string" }, "model": { "type": "string" }, "year": { "type": "integer" }, "hours": { "type": "integer" }, "condition": { "type": "string" } } }, "seller": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" }, "country": { "type": "string" } } }, "image": { "type": "string" }, "location": { "type": "string" } } } } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # Model Context Protocol The **Model Context Protocol (MCP)** lets AI assistants call **Piloterr** as **tools**: same operations as the REST API, with your **API key**. You can document setup like many teams do: a short README, a sample **`mcp.json`**, and copy-paste steps for your users. What you need [#what-you-need] * A **Piloterr** account ([register](https://app.piloterr.com/register) if needed) and access to the [dashboard](https://app.piloterr.com). * An **API key** with the **`x-api-key`** header (see [API Keys](/api-keys)). * **MCP endpoint:** **`https://mcp.piloterr.com/`** How it works [#how-it-works] The server uses **Streamable HTTP** at **`https://mcp.piloterr.com/`**. It is not a normal web page. Each **tool** maps to an API operation; billing and behaviour match the REST API. Use the rest of this documentation for endpoints and parameters. Claude Code [#claude-code] Official docs: [Model Context Protocol (MCP)](https://code.claude.com/docs/en/mcp). Example: **`claude mcp add --transport http piloterr https://mcp.piloterr.com/`** with **`--header`** **`x-api-key: YOUR_API_KEY`**. Use the same URL as in the Cursor section below. Cursor [#cursor] See the [Cursor MCP documentation](https://cursor.com/docs/mcp). In **Settings → MCP**, add an **HTTP** server, or use a project **`mcp.json`** with a **`url`** (ending in `/`) and **`headers`** for your API key. Use the **MCP endpoint** for **Piloterr** below. Never commit secrets. Prefer environment-specific config or a placeholder like `YOUR_API_KEY`. ```json { "mcpServers": { "piloterr": { "url": "https://mcp.piloterr.com/", "headers": { "x-api-key": "YOUR_API_KEY" } } } } ``` Gemini CLI [#gemini-cli] See [MCP server](https://geminicli.com/docs/tools/mcp-server/) in the Gemini CLI documentation. Point the client at **`https://mcp.piloterr.com/`** and pass your API key (for example via **`x-api-key`**) as the tool docs describe. OpenAI Developer Mode [#openai-developer-mode] See [Developer mode](https://developers.openai.com/api/docs/guides/developer-mode) in the OpenAI API documentation. Wire MCP tools to **`https://mcp.piloterr.com/`** and your **API key** following that guide. See also [#see-also] * [API Keys](/api-keys): create and manage keys * [Best practices](/best-practices): secure integration # Oceanio Search **GET** `https://api.piloterr.com/v2/oceanio/search` **Credit cost:** 1 credit per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | | ## Responses ### 200 Successful response ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # Ovoko Ad **GET** `https://api.piloterr.com/v2/ovoko/ad` Extract full details from an Ovoko auto parts listing including price, part info, seller data, compatibility list, and stock availability. **Credit cost:** 1 credit per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | Full Ovoko product listing URL for a specific auto part. **Supported domains:** `ovoko.fr`, `ovoko.de`, `ovoko.es`, `ovoko.it`, `ovoko.pl`, `ovoko.pt`, `ovoko.ro`, `ovoko.lt`, `ovoko.lv`, `ovoko.ee` **Example:** https://www.ovoko.fr/fr/annonce/filtre-a-huile-mann-filter-w71930-128549 **Note:** The URL must point to a specific part listing page. Category and search pages are not supported by this endpoint — use the search endpoint instead. | ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "price": { "type": "object", "properties": { "amount": { "type": "number" }, "currency": { "type": "string" }, "formatted": { "type": "string" } } }, "seller": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "location": { "type": "object", "properties": { "city": { "type": "string" }, "country": { "type": "string" } } }, "rating": { "type": "number" }, "reviews_count": { "type": "integer" } } }, "part": { "type": "object", "properties": { "brand": { "type": "string" }, "reference": { "type": "string" }, "condition": { "type": "string" }, "category": { "type": "string" }, "compatibility": { "type": "array", "items": { "type": "string" } }, "ean": { "type": "string" }, "weight_kg": { "type": "number" }, "dimensions_mm": { "type": "object", "properties": { "length": { "type": "integer" }, "width": { "type": "integer" }, "height": { "type": "integer" } } } } }, "stock": { "type": "object", "properties": { "available": { "type": "boolean" }, "quantity": { "type": "integer" }, "delivery_days": { "type": "integer" } } }, "images": { "type": "array", "items": { "type": "string" } }, "description": { "type": "string" }, "url": { "type": "string" } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # Ovoko Search **GET** `https://api.piloterr.com/v2/ovoko/search` Search for auto parts on Ovoko by URL, returning paginated listings with part details, pricing, seller rating, and stock availability. **Credit cost:** 1 credit per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | Full Ovoko search or category URL for auto parts. **Supported domains:** `ovoko.fr`, `ovoko.de`, `ovoko.es`, `ovoko.it`, `ovoko.pl`, `ovoko.pt`, `ovoko.ro`, `ovoko.lt`, `ovoko.lv`, `ovoko.ee` **Example (keyword search):** https://www.ovoko.fr/fr/recherche?q=filtre+huile **Example (category browse):** https://www.ovoko.fr/fr/categorie/filtration/filtres-a-huile **Note:** Pagination can be added by appending `?page=2` to the URL. | ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "total": { "type": "integer" }, "page": { "type": "integer" }, "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string" }, "price": { "type": "object", "properties": { "amount": { "type": "number" }, "currency": { "type": "string" }, "formatted": { "type": "string" } } }, "part": { "type": "object", "properties": { "brand": { "type": "string" }, "reference": { "type": "string" }, "condition": { "type": "string" } } }, "seller": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" }, "rating": { "type": "number" } } }, "stock": { "type": "object", "properties": { "available": { "type": "boolean" }, "delivery_days": { "type": "integer" } } }, "image": { "type": "string" } } } } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # Owler Company Info **GET** `https://api.piloterr.com/v2/owler/company/info` Retrieve detailed company intelligence from Owler, including revenue, employee count, CEO info, competitors, funding, and industry sectors. **Credit cost:** 1 credit per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | The company to look up on Owler. Multiple formats are accepted: - **Company slug:** `airbus` - **Owler company URL:** `https://owler.com/company/airbus` **Examples:** https://owler.com/company/tesla The response includes the company's financials, CEO details, headcount, competitors, and industry sectors. | ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "cg": { "type": "array", "items": { "type": "object", "properties": { "founded": { "type": "string" }, "revenue": { "type": "integer" }, "ownership": { "type": "string" }, "ceo_detail": { "type": "object", "properties": { "ceo_pic": { "type": "string" }, "last_name": { "type": "string" }, "ceo_rating": { "type": "integer" }, "first_name": { "type": "string" }, "designation": { "type": "string" } } }, "headquarters": { "type": "object", "properties": { "city": { "type": "string" }, "state": { "type": "string" }, "country": { "type": "string" }, "state_display_name": { "type": "string" } } }, "revenue_range": { "type": "string" }, "total_funding": { "type": "integer" }, "employee_count": { "type": "integer" }, "employee_range": { "type": "string" }, "industry_sectors": { "type": "array", "items": { "type": "string" } }, "formatted_funding": { "type": "string" }, "formatted_revenue": { "type": "string" }, "company_basic_info": { "type": "object", "properties": { "logo": { "type": "string" }, "cp_link": { "type": "string" }, "website": { "type": "string" }, "team_name": { "type": "string" }, "company_id": { "type": "integer" }, "short_name": { "type": "string" } } }, "formatted_employee_count": { "type": "string" } } } } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # Owler Search **GET** `https://api.piloterr.com/v2/owler/search` Search for companies on Owler by name or keyword, returning a list of matching companies with slugs, logos, domains, and profile URLs. **Credit cost:** 1 credit per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | The company name or keyword to search for on Owler. **Examples:** tesla The API returns a list of matching companies from Owler's database, including their name, slug, logo, domain, and Owler profile URL. | ## Responses ### 200 Successful response ```json { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "logo": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "domain": { "type": "string" } } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # PagesJaunes Page Info **GET** `https://api.piloterr.com/v2/pagesjaunes/page/info` Retrieve detailed business information from a PagesJaunes page, including contact details, opening hours, services, payment methods, and SIREN number. **Credit cost:** 1 credit per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | A PagesJaunes business page URL or business ID. **Examples:** https://www.pagesjaunes.fr/pros/56824689 Both the full PagesJaunes URL and the numeric business ID are accepted. | ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "url": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" }, "address": { "type": "string" }, "activity": { "type": "string" }, "services": { "type": "array", "items": { "type": "string" } }, "websites": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "type": { "type": "string" } } } }, "business_info": { "type": "object", "properties": { "siren": { "type": "string" }, "forme_juridique": { "type": "string" }, "effectif_entreprise": { "type": "string" }, "creation_d_entreprise": { "type": "string" } } }, "opening_hours": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "string" }, "hours": { "type": "string" } } } }, "payment_methods": { "type": "array", "items": { "type": "string" } } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # PagesJaunes Search **GET** `https://api.piloterr.com/v2/pagesjaunes/search` Search PagesJaunes for French local businesses by category and location, returning paginated results with contact details and ratings. **Credit cost:** 1 credit per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | A valid PagesJaunes search URL. **Example:** https://www.pagesjaunes.fr/annuaire/chercherlespros?quoiqui=Dentiste&ou=Toulouse+(31000)&univers=pagesjaunes&idOu= You can customize the search by changing the `quoiqui` (what/who) and `ou` (where) parameters in the URL. **Note:** URL-encode the `&` as `%26` when passing the full URL as a GET parameter value. | ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "name": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "address": { "type": "string" }, "activity": { "type": "string" }, "image_url": { "type": "string" } } } }, "pagination": { "type": "object", "properties": { "next": { "type": "integer" }, "current": { "type": "integer" }, "other_pages": { "type": "array", "items": { "type": "integer" } }, "total_pages": { "type": "integer" }, "has_next_page": { "type": "boolean" } } } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # Pinterest User Info **GET** `https://api.piloterr.com/v2/pinterest/user/info` Access Pinterest user profiles and analytics for targeted marketing and audience insights. **Credit cost:** 1 credit per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | The Pinterest profile to retrieve. Accepts a full profile URL or a username. **Accepted formats:** - `https://www.pinterest.com/amandagabriella` — full profile URL - `amandagabriella` — username only **Example:** https://www.pinterest.com/amandagabriella **Notes:** - **Private accounts:** Pinterest does not have private accounts — all public profiles are accessible. - **Deactivated accounts:** Returns a not-found error if the account no longer exists. | ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "name": { "type": "string" }, "avatar": { "type": "string" }, "website": { "nullable": true }, "pin_count": { "type": "integer" }, "created_at": { "type": "string" }, "board_count": { "type": "integer" }, "description": { "nullable": true }, "is_verified": { "type": "boolean" }, "profile_cover": { "nullable": true }, "follower_count": { "type": "integer" }, "domain_verified": { "type": "boolean" } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # ProductHunt Product Info **GET** `https://api.piloterr.com/v2/producthunt/product/info` Retrieve product data from ProductHunt, including tagline, categories, screenshots, reviews rating, and social links. **Status:** Degraded **Credit cost:** 1 credit per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | A ProductHunt product URL or product slug. **Examples:** https://www.producthunt.com/products/miro Both the full ProductHunt URL and the product slug are accepted. | ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "id": { "type": "string" }, "logo": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "tagline": { "type": "string" }, "categories": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } } }, "description": { "type": "string" }, "posts_count": { "type": "integer" }, "screenshots": { "type": "array", "items": { "type": "string" } }, "pricing_type": { "nullable": true }, "social_links": { "type": "object", "properties": { "website": { "type": "string" } } }, "reviews_rating": { "type": "number" }, "reviewers_count": { "type": "integer" } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # Rocketreack Company Info **GET** `https://api.piloterr.com/v2/rocketreach/company/info` Rocketreack Company Info via API. **Credit cost:** 1 credit per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | | ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "name": { "type": "string" }, "domain": { "type": "string" }, "ticker": { "type": "string" }, "address": { "type": "string" }, "founded": { "type": "integer" }, "funding": { "type": "string" }, "revenue": { "type": "string" }, "website": { "type": "string" }, "code_sic": { "type": "array", "items": { "type": "string" } }, "keywords": { "type": "array", "items": { "type": "string" } }, "code_naics": { "type": "array", "items": { "type": "string" } }, "industries": { "type": "array", "items": { "type": "string" } }, "competitors": { "type": "array", "items": { "type": "string" } }, "description": { "type": "string" }, "phone_number": { "type": "string" }, "email_formats": { "type": "array", "items": { "type": "object", "properties": { "format": { "type": "string" }, "example": { "type": "string" }, "percentage": { "type": "string" } } } }, "employee_count": { "type": "integer" }, "social_networks": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "name": { "type": "string" } } } }, "related_companies": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "name": { "type": "string" } } } } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # SeLoger Agency Rent **GET** `https://api.piloterr.com/v2/seloger/agency/rent` Retrieve paginated rental property listings published by a specific SeLoger agency using its numeric agency ID. **Credit cost:** 2 credits per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | A valid SeLoger agency ID. **Example:** 18317 **Note:** The agency ID is the numeric identifier found at the end of SeLoger agency profile URLs (e.g. `https://www.seloger.com/.../agence-18317/`). You can find it on any agency page. | | `page` | query | `number` | No | Page number for paginating through the agency's rental listings. Use this parameter to iterate through multiple pages of results when the agency has more listings than returned in a single call. **Example:** 2 | ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "count": { "type": "integer" }, "result": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "type": { "type": "integer" }, "image": { "type": "object", "properties": { "alt": { "nullable": true }, "src": { "type": "string" } } }, "price": { "type": "integer" }, "surface": { "type": "integer" }, "rooms_count": { "type": "integer" }, "bedrooms_count": { "type": "integer" }, "locality_label": { "type": "string" } } } } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # SeLoger Agency Sale **GET** `https://api.piloterr.com/v2/seloger/agency/sale` Retrieve paginated sale property listings published by a specific SeLoger agency using its numeric agency ID. **Credit cost:** 2 credits per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | A valid SeLoger agency ID. **Example:** 18317 **Note:** The agency ID is the numeric identifier found at the end of SeLoger agency profile URLs (e.g. `https://www.seloger.com/.../agence-18317/`). You can retrieve it from any SeLoger agency page. | | `page` | query | `number` | No | Page number for paginating through the agency's sale listings. Use this parameter to iterate through multiple pages when the agency has more listings than returned in a single call. **Example:** 2 | ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "count": { "type": "integer" }, "result": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "type": { "type": "integer" }, "image": { "type": "object", "properties": { "alt": { "nullable": true }, "src": { "type": "string" } } }, "price": { "type": "integer" }, "surface": { "type": "integer" }, "rooms_count": { "type": "integer" }, "bedrooms_count": { "type": "integer" }, "locality_label": { "type": "string" } } } } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # SeLoger Agency **GET** `https://api.piloterr.com/v2/seloger/agency` Retrieve detailed profile information for a SeLoger real estate agency including contact details, ratings, reviews, and address. **Credit cost:** 2 credits per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | A valid SeLoger agency profile URL. **Supported URL formats:** - `/professionnels/agences-immobilieres/{city}/{slug}/` - `/professionnels/agents-commerciaux/{city}/{slug}/` **Example:** https://www.seloger.com/professionnels/agences-immobilieres/castanet-tolosan-31320/agence-21719 **Note:** The URL must point to a SeLoger agency profile page. The agency slug and numeric ID are both embedded in the URL. | ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "id": { "type": "string" }, "logo": { "type": "object", "properties": { "alt": { "type": "string" }, "src": { "type": "string" } } }, "name": { "type": "string" }, "email": { "type": "string" }, "siret": { "type": "string" }, "banner": { "type": "object", "properties": { "alt": { "type": "string" }, "src": { "nullable": true } } }, "id_rcu": { "type": "string" }, "rating": { "type": "object", "properties": { "value": { "type": "number" }, "reviews_count": { "type": "integer" } } }, "address": { "type": "object", "properties": { "city": { "type": "string" }, "street": { "type": "string" }, "zip_code": { "type": "string" } } }, "fee_url": { "type": "string" }, "reviews": { "type": "object", "properties": { "count": { "type": "integer" }, "result": { "type": "array", "items": {} } } }, "website": { "type": "string" }, "id_tiers": { "type": "string" }, "is_seller": { "nullable": true }, "languages": { "type": "string" }, "legal_form": { "nullable": true }, "sold_count": { "nullable": true }, "agency_type": { "type": "integer" }, "description": { "nullable": true }, "phone_number": { "type": "string" }, "intermediary_id": { "type": "integer" }, "social_networks": { "type": "array", "items": {} }, "sold_properties": { "nullable": true }, "intermediary_type": { "type": "integer" }, "environment_source": { "type": "string" }, "head_office_address": { "nullable": true } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # SeLoger Property **GET** `https://api.piloterr.com/v2/seloger/property` Efficiently extract detailed data from a SeLoger real estate listing including agency info, pricing, photos, description, and property criteria. **Credit cost:** 2 credits per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | A valid SeLoger property listing URL. **Example:** https://www.seloger.com/annonces/achat/appartement/bordeaux-33/capucins-saint-michel-nansouty-saint-genes/234462129.htm **Note:** The URL must point to an active SeLoger property listing page. Expired or removed listings will return an error. Both sale and rental listing URLs are supported. | | `return_page_source` | query | `boolean` | No | Whether to return the raw HTML source of the property page instead of parsed JSON data. - `false`: Returns structured JSON data (default) - `true`: Returns the raw HTML source of the page **Note:** Enabling this option is useful for custom parsing or debugging, but the response will not be structured JSON. | ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "agency": { "type": "object", "properties": { "id": { "type": "integer" }, "logo": { "type": "string" }, "name": { "type": "string" }, "id_rcu": { "type": "string" }, "rating": { "type": "object", "properties": { "rating": { "type": "number" }, "review_url": { "type": "string" }, "review_count": { "type": "integer" } } }, "address": { "type": "string" }, "tier_id": { "type": "integer" }, "fees_url": { "type": "string" }, "description": { "nullable": true }, "website_url": { "type": "string" }, "legal_notice": { "type": "object", "properties": { "rcs_siren": { "type": "string" }, "legal_form": { "nullable": true }, "is_individual": { "type": "boolean" }, "share_capital": { "type": "integer" }, "social_reason": { "type": "string" }, "headquarter_address": { "type": "string" }, "financial_guarantee_fund": { "type": "string" }, "professional_card_number": { "nullable": true }, "financial_guarantee_amount": { "type": "integer" }, "professional_card_prefecture": { "nullable": true } } }, "phone_number": { "type": "string" }, "contact_hidden": { "type": "boolean" }, "profession_type": { "type": "string" }, "profil_page_url": { "type": "string" }, "organisation_logo": { "nullable": true } } }, "seeker": { "nullable": true }, "contact": { "type": "object", "properties": { "book_a_visit": { "type": "object", "properties": { "slots": { "nullable": true }, "enabled": { "type": "boolean" }, "event_type": { "nullable": true }, "required_form": { "type": "boolean" }, "plato_agency_id": { "nullable": true }, "allowed_contracts": { "nullable": true }, "unpaid_rent_garanty": { "type": "boolean" }, "unpaid_rent_garanty_rate": { "type": "integer" } } } } }, "listing": { "type": "object", "properties": { "url": { "type": "object", "properties": { "value": { "type": "string" }, "nature": { "type": "integer" }, "business_unit_type": { "type": "string" } } }, "early_access": { "nullable": true }, "listing_detail": { "type": "object", "properties": { "id": { "type": "integer" }, "media": { "type": "object", "properties": { "photos": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "mobile_url": { "type": "string" }, "square_url": { "type": "string" }, "default_url": { "type": "string" }, "original_url": { "type": "string" }, "is_horizontal": { "type": "boolean" }, "descriptive_fr": { "nullable": true }, "square_large_url": { "type": "string" }, "low_resolution_url": { "type": "string" }, "photo_description_tags": { "nullable": true } } } } } } } } } } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # SeLoger Search **GET** `https://api.piloterr.com/v2/seloger/search` Efficiently extract real estate listings from SeLoger search pages for market insights, property management, and investment analysis. **Credit cost:** 2 credits per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | A valid SeLoger search results URL. Any SeLoger search page URL with filters is supported — location, property type, price range, surface, and number of rooms can all be embedded in the URL. **Supported transaction types:** - `/annonces/achat/` — property for sale - `/annonces/locations/` — property for rent **Example:** https://www.seloger.com/annonces/achat/appartement/bordeaux-33/ **Notes:** - Pagination parameters can be appended directly to the URL - All filters visible in the SeLoger search interface are supported | | `return_page_source` | query | `boolean` | No | Whether to return the raw HTML source of the search results page instead of parsed JSON data. - `false`: Returns structured JSON array of listings (default) - `true`: Returns the raw HTML source of the page **Default:** `false` **Note:** Useful for debugging or custom parsing workflows. | ## Responses ### 200 Successful response ```json { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "epc": { "nullable": true }, "tags": { "type": "array", "items": { "type": "string" } }, "rooms": { "type": "integer" }, "title": { "type": "string" }, "is_new": { "type": "boolean" }, "nature": { "type": "integer" }, "photos": { "type": "array", "items": { "type": "string" } }, "contact": { "type": "object", "properties": { "email": { "type": "string" }, "id_rcu": { "type": "string" }, "img_url": { "type": "string" }, "agency_id": { "type": "integer" }, "agency_link": { "nullable": true }, "agency_page": { "nullable": true }, "contact_name": { "type": "string" }, "phone_number": { "type": "string" }, "is_private_seller": { "type": "boolean" } } }, "pricing": { "type": "object", "properties": { "price": { "type": "string" }, "lifetime": { "type": "boolean" }, "raw_price": { "type": "string" }, "price_note": { "nullable": true }, "monthly_price": { "type": "integer" }, "square_meter_price": { "type": "string" } } }, "surface": { "type": "number" }, "position": { "type": "integer" }, "zip_code": { "type": "string" }, "card_type": { "type": "string" }, "transport": { "nullable": true }, "city_label": { "type": "string" }, "desk_count": { "type": "integer" }, "photos_qty": { "type": "integer" }, "description": { "type": "string" }, "estate_type": { "type": "string" }, "video_u_r_l": { "nullable": true }, "early_access": { "nullable": true }, "is_exclusive": { "type": "boolean" }, "bedroom_count": { "type": "integer" }, "business_unit": { "type": "integer" }, "housing_batch": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string" } } } }, "lease_type_id": { "type": "integer" }, "district_label": { "type": "string" }, "estate_type_id": { "type": "integer" }, "publication_id": { "type": "integer" }, "classified_u_r_l": { "type": "string" }, "optional_criteria": { "type": "array", "items": {} }, "partner_link_type": { "type": "integer" }, "highlighting_level": { "type": "integer" }, "forced_intermediary": { "type": "boolean" }, "transaction_type_id": { "type": "integer" }, "virtual_visit_u_r_l": { "type": "string" }, "missing_optional_criteria": { "type": "array", "items": {} } } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # Shophouzz Product **GET** `https://api.piloterr.com/v2/shophouzz/product` Shophouzz Product via API. **Credit cost:** 1 credit per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | | ## Responses ### 200 Successful response ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # Shopify Apps **GET** `https://api.piloterr.com/v2/shopify/apps` Retrieve structured details about any Shopify App Store listing, including title, logo, screenshots, pricing plans, categories, and description. **Credit cost:** 1 credit per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | URL of the Shopify App Store listing to scrape. **Example:** https://apps.shopify.com/judgeme **Notes:** - The URL must point to a valid listing on `apps.shopify.com`. - The API returns the app title, handle, logo, screenshots, description, pricing plans, and categories. - The app handle is the slug at the end of the URL (e.g. `judgeme` in `https://apps.shopify.com/judgeme`). | ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "url": { "type": "string" }, "logo": { "type": "string" }, "title": { "type": "string" }, "handle": { "type": "string" }, "images": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "description": { "type": "string" } } } }, "pricing": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "price": { "type": "string" }, "features": { "type": "array", "items": { "type": "string" } } } } }, "categories": { "type": "array", "items": {} }, "description": { "type": "string" } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # Shopify Product **GET** `https://api.piloterr.com/v2/shopify/product` Extract full product details from any Shopify store product page, including title, variants, pricing, images, inventory, and options. **Credit cost:** 1 credit per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | URL of a Shopify product page to scrape. **Example:** https://www.decathlon.com/products/simond-backpacking-sleeping-bag-mt500-41-f-synthetic-346446 **Notes:** - The URL must point to a product page on any Shopify-powered store (not limited to a single domain). - The API works with any public Shopify storefront that exposes the standard `products.json` endpoint. - The response includes full product details: title, vendor, variants, images, options, pricing, and inventory. | ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "id": { "type": "integer" }, "tags": { "type": "string" }, "image": { "type": "object", "properties": { "id": { "type": "integer" }, "alt": { "type": "string" }, "src": { "type": "string" }, "width": { "type": "integer" }, "height": { "type": "integer" }, "position": { "type": "integer" }, "created_at": { "type": "string" }, "product_id": { "type": "integer" }, "updated_at": { "type": "string" } } }, "title": { "type": "string" }, "handle": { "type": "string" }, "vendor": { "type": "string" }, "options": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "values": { "type": "array", "items": { "type": "string" } }, "position": { "type": "integer" }, "product_id": { "type": "integer" } } } }, "variants": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "sku": { "type": "string" }, "grams": { "type": "integer" }, "price": { "type": "string" }, "title": { "type": "string" }, "weight": { "type": "number" }, "barcode": { "type": "string" }, "option1": { "type": "string" }, "option2": { "type": "string" }, "taxable": { "type": "boolean" }, "position": { "type": "integer" }, "created_at": { "type": "string" }, "product_id": { "type": "integer" }, "updated_at": { "type": "string" }, "weight_unit": { "type": "string" }, "compare_at_price": { "type": "string" }, "inventory_policy": { "type": "string" }, "requires_shipping": { "type": "boolean" }, "inventory_quantity": { "type": "integer" }, "fulfillment_service": { "type": "string" }, "inventory_management": { "type": "string" } } } }, "body_html": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "product_type": { "type": "string" }, "published_at": { "type": "string" }, "published_scope": { "type": "string" }, "template_suffix": { "type": "string" } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # SimilarWeb Domain **GET** `https://api.piloterr.com/v2/similarweb/domain` Retrieve website traffic and engagement metrics for any domain from SimilarWeb, including visits, bounce rate, top keywords, and traffic sources. **Credit cost:** 1 credit per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | A domain name to retrieve traffic and engagement metrics for. **Examples:** google.com Provide the bare domain without `https://` or `www.` prefixes. | ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "title": { "type": "string" }, "category": { "type": "string" }, "site_name": { "type": "string" }, "engagments": { "type": "object", "properties": { "year": { "type": "string" }, "month": { "type": "string" }, "visits": { "type": "string" }, "bounce_rate": { "type": "string" }, "time_on_site": { "type": "string" }, "page_per_visit": { "type": "string" } } }, "global_rank": { "type": "object", "properties": { "rank": { "type": "integer" } } }, "country_rank": { "type": "object", "properties": { "rank": { "type": "integer" }, "country": { "type": "integer" }, "country_code": { "type": "string" } } }, "top_keywords": { "type": "array", "items": { "type": "object", "properties": { "cpc": { "type": "number" }, "name": { "type": "string" }, "volume": { "type": "integer" }, "estimated_value": { "type": "integer" } } } }, "category_rank": { "type": "object", "properties": { "rank": { "type": "string" }, "category": { "type": "string" } } }, "snapshot_date": { "type": "string" }, "traffic_sources": { "type": "object", "properties": { "mail": { "type": "number" }, "direct": { "type": "number" }, "search": { "type": "number" }, "social": { "type": "number" }, "referrals": { "type": "number" }, "paid_referrals": { "type": "number" } } }, "large_screenshot": { "type": "string" }, "top_country_shares": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "number" }, "country": { "type": "integer" }, "country_code": { "type": "string" } } } } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # Similarweb Search **GET** `https://api.piloterr.com/v2/similarweb/search` Search the Similarweb database to retrieve websites, companies, mobile apps, search keywords, and technologies associated with a given domain or keyword. **Credit cost:** 1 credit per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | Domain name or keyword to search for in the Similarweb database. **Example:** google.com **Notes:** - **Domain search:** Use a full domain (e.g. `google.com`) to find related websites, apps, companies, and technologies associated with that domain. - **Keyword search:** Use a plain keyword (e.g. `amazon`) to retrieve broader associations across the Similarweb index. | ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "apps": { "type": "object", "properties": { "appStore": { "type": "array", "items": {} }, "googlePlay": { "type": "array", "items": {} } } }, "keywords": { "type": "array", "items": { "type": "string" } }, "websites": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "image": { "type": "string" }, "isVirtual": { "type": "boolean" } } } }, "companies": { "type": "array", "items": {} }, "technologies": { "type": "array", "items": {} } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # Status Codes Billing applies to successful requests: `200` for synchronous calls, `201` for asynchronous jobs, and `404` when the resource is not found (unless specified otherwise in the API documentation). | Code | Billed | Status | Action | | ----- | ------ | ------------------- | -------------------------------------------------------------------------------------------------------- | | `200` | Yes | Successful API Call | No action required. | | `201` | Yes | Job Created | No action required. | | `202` | No | Accepted (Async) | The request was accepted and is being processed. Use the job ID to check the status. | | `400` | No | Bad Request | Verify your parameters and their types. Check the documentation for more information. | | `401` | No | Invalid API Key | Check your API key (`x-api-key` header or `x_api_key` query string). | | `401` | No | Inactive API Key | Activate your API key in the API Keys section of your account settings. | | `401` | No | Expired API Key | Update your API key or generate a new one. | | `401` | No | Rate Limit Exceeded | Consider upgrading your current plan or contact our sales team. | | `402` | No | Payment Required | Settle any outstanding invoices to continue using the API. | | `403` | No | Forbidden | Verify your permissions. Contact us if you believe this is a mistake. | | `404` | Varies | Not Found | Billing is endpoint-specific. Check the individual endpoint documentation. | | `413` | No | Payload Too Large | The uploaded file or request body exceeds the size limit. Check the API documentation for maximum sizes. | | `500` | No | Internal Error | Retry the action or contact our support team. | # StockX Product **GET** `https://api.piloterr.com/v2/stockx/product` Retrieve detailed product information from StockX, including market prices, bid/ask data, size variants, and product metadata. **Credit cost:** 2 credits per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | A StockX product slug. **Examples:** nike-air-max-1-travis-scott-wheat **Note:** Use product slugs, not internal UUIDs (e.g. do NOT use `c318bbcc-312a-4396-9252-698c203d1dea`). Find slugs in the product URL on stockx.com. | | `country` | query | `string` | No | Country code for localized pricing and availability. - `US`: United States (default) - `FR`: France - `GB`: United Kingdom - `SV`: El Salvador **Example:** `US` | | `currency` | query | `string` | No | Currency code for price display. - `USD`: US Dollar (default) - `EUR`: Euro - `GBP`: British Pound **Example:** `USD` | | `language` | query | `string` | No | Language code for localized content. - `en-US`: English (default) - `fr-FR`: French - `en-GB`: British English **Example:** `en-US` | ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "id": { "type": "string" }, "sku": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "brand": { "type": "string" }, "image": { "type": "string" }, "model": { "type": "string" }, "gender": { "type": "string" }, "market": { "type": "object", "properties": { "bids": { "type": "object", "properties": { "lowest_ask": { "type": "integer" }, "highest_bid": { "type": "integer" }, "number_asks": { "type": "integer" }, "number_bids": { "type": "integer" } } }, "sales": { "type": "object", "properties": { "last_sale": { "type": "integer" }, "sales_last_72h": { "type": "integer" } } } } }, "category": { "type": "string" }, "primary_category": { "type": "string" }, "description": { "type": "string" }, "traits": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "value": { "type": "string" } } } } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # StockX Search **GET** `https://api.piloterr.com/v2/stockx/search` Search StockX for products by name, brand, SKU, or slug and receive a list of matching items with product IDs, slugs, images, and colorways. **Credit cost:** 2 credits per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | Search query for StockX products. Can be a product name, brand, SKU, or slug. **Examples:** Air Jordan Retro All three formats are supported: keyword phrases, style codes (SKU), and product slugs. | ## Responses ### 200 Successful response ```json { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "slug": { "type": "string" }, "name": { "type": "string" }, "sku": { "type": "string" }, "category": { "type": "string" }, "brand": { "type": "string" }, "image": { "type": "string" }, "colorway": { "type": "string" } } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # StockX Trends **GET** `https://api.piloterr.com/v2/stockx/trends` Retrieve trending products on StockX by category, with options to sort by featured, most active, or release date. **Credit cost:** 2 credits per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | StockX product category to retrieve trending items for. Accepted values: - `sneakers`: Trending sneakers - `streetwear`: Trending streetwear - `electronics`: Trending electronics - `trading cards`: Trending trading cards - `collectibles`: Trending collectibles - `apparel`: Trending apparel - `handbags`: Trending handbags - `watches`: Trending watches | | `sort_by` | query | `string` | No | Sort order for trending results. - `featured`: Featured/curated items (default) - `most_active`: Most actively traded items - `release_date`: Newest releases first | | `country` | query | `string` | No | Country code for localized trending data. - `US`: United States - `FR`: France - `GB`: United Kingdom | ## Responses ### 200 Successful response ```json { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "slug": { "type": "string" }, "name": { "type": "string" }, "brand": { "type": "string" }, "sku": { "type": "string" }, "image": { "type": "string" }, "category": { "type": "string" }, "release_date": { "type": "string" } } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # Trustpilot Company Info **GET** `https://api.piloterr.com/v2/trustpilot/company/info` Retrieve Trustpilot company profile data, including trust score, star rating, categories, contact info, and review response behavior. **Credit cost:** 1 credit per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | A Trustpilot company URL or domain name. **Examples:** https://www.trustpilot.com/review/nordvpn.com Both the full Trustpilot review URL and the company domain are accepted. | ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "id": { "type": "string" }, "stars": { "type": "integer" }, "trust_score": { "type": "number" }, "display_name": { "type": "string" }, "website_url": { "type": "string" }, "website_title": { "type": "string" }, "is_claimed": { "type": "boolean" }, "is_closed": { "type": "boolean" }, "contact_info": { "type": "object", "properties": { "city": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "country": { "type": "string" } } }, "categories": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "rank": { "type": "string" }, "is_primary": { "type": "boolean" } } } }, "breadcrumb": { "type": "object", "properties": { "top_level_display_name": { "type": "string" }, "mid_level_display_name": { "type": "string" }, "bottom_level_display_name": { "type": "string" } } }, "activity": { "type": "object", "properties": { "is_claimed": { "type": "boolean" }, "reply_behavior": { "type": "object", "properties": { "reply_percentage": { "type": "number" }, "average_days_to_reply": { "type": "number" } } } } }, "similar_business": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "domain": { "type": "string" } } } } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # Usage The Usage endpoint lets you check your remaining credits, subscription quota, rate limits, and API key details at any time. It does not consume any credits. This endpoint is free. It never consumes any credits. Request [#request] ```bash curl "https://api.piloterr.com/v2/usage" \ -H "x-api-key: YOUR_API_KEY" ``` Response Fields [#response-fields] | Field | Type | Description | | --------------------------- | ----------------- | ------------------------------------------------------------ | | `remaining` | `integer` | Credits available right now | | `total_used` | `integer` | Credits consumed in the current billing period | | `renewal_date` | `string` | Date when the subscription renews (ISO 8601) | | `period.start` | `string` | Start of the current billing period | | `period.end` | `string` | End of the current billing period | | `subscription.used` | `integer` | Subscription calls used | | `subscription.total` | `integer` | Subscription call quota | | `subscription.remaining` | `integer` | Subscription calls remaining | | `subscription.percent_used` | `number` | Percentage of subscription quota consumed | | `credits.given` | `integer` | Extra credits added to your account | | `credits.consumed` | `integer` | Extra credits consumed | | `credits.remaining` | `integer` | Extra credits remaining | | `rate_limit.per_minute` | `integer \| null` | Requests per minute limit (`null` = unlimited) | | `rate_limit.per_second` | `integer \| null` | Requests per second limit (`null` = unlimited) | | `account.name` | `string` | Name of the account | | `account.slug` | `string` | Account identifier slug | | `api_key.alias` | `string` | Friendly name of the API key | | `api_key.active` | `boolean` | Whether the key is currently active | | `api_key.category` | `string` | Key category (e.g. `development`, `production`) | | `api_key.expires` | `string \| null` | Expiry date of the key (`null` = never expires) | | `api_key.quotas` | `object` | Custom per-key quotas: `total`, `daily`, `weekly`, `monthly` | Example Response [#example-response] ```json { "remaining": 450, "total_used": 1550, "renewal_date": "2026-04-25", "period": { "start": "2026-03-25", "end": "2026-04-25" }, "subscription": { "used": 1550, "total": 2000, "remaining": 450, "percent_used": 77 }, "credits": { "given": 0, "consumed": 0, "remaining": 0, "percent_used": 0 }, "rate_limit": { "per_minute": null, "per_second": null }, "account": { "name": "Acme Corp", "slug": "acme-corp" }, "api_key": { "alias": "production", "active": true, "category": "production", "expires": null, "quotas": { "total": null, "daily": null, "weekly": null, "monthly": null } } } ``` # Vinted User Info **GET** `https://api.piloterr.com/v2/vinted/user/info` Retrieve public profile information for a Vinted user by profile URL or user ID, including item count, followers, location, and verification status. **Status:** Deprecated **Credit cost:** 1 credit per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | Vinted user profile URL or numeric user ID. Accepted formats: - `URL`: full Vinted member URL (e.g. `https://www.vinted.fr/member/133607xx-xx`) - `ID`: numeric Vinted user ID (e.g. `133607`) **Examples:** https://www.vinted.fr/member/133607xx-xx 133607 **Notes:** - Both the full profile URL and the numeric ID are supported. - The response includes the user's public profile data: location, item count, followers, following, and identity verification statuses. | ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "id": { "type": "integer" }, "city": { "type": "string" }, "items": { "type": "integer" }, "login": { "type": "string" }, "country": { "type": "string" }, "business": { "nullable": true }, "username": { "type": "string" }, "followers": { "type": "integer" }, "following": { "type": "integer" }, "verification": { "type": "object", "properties": { "email": { "type": "object", "properties": { "valid": { "type": "boolean" }, "available": { "type": "boolean" } } }, "phone": { "type": "object", "properties": { "valid": { "type": "boolean" }, "available": { "type": "boolean" }, "verified_at": { "type": "string" } } }, "google": { "type": "object", "properties": { "valid": { "type": "boolean" }, "available": { "type": "boolean" }, "verified_at": { "type": "string" } } }, "facebook": { "type": "object", "properties": { "valid": { "type": "boolean" }, "available": { "type": "boolean" }, "verified_at": { "type": "string" } } } } } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # Walmart Product **GET** `https://api.piloterr.com/v2/walmart/product` Extract full product details from a Walmart product page, including pricing, brand, images, customer reviews, and availability. **Credit cost:** 1 credit per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | Full Walmart product page URL. **Example:** https://www.walmart.com/ip/Adidas-Moves-Body-Spray-for-Men-2-5-Oz/710726462 **Notes:** - The URL must point to a Walmart product detail page containing `/ip/` in the path - The numeric ID at the end of the URL is the Walmart item ID | ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "sku": { "type": "string" }, "name": { "type": "string" }, "brand": { "type": "object", "properties": { "name": { "type": "string" } } }, "image": { "type": "string" }, "model": { "type": "string" }, "gtin13": { "nullable": true }, "offers": { "type": "object", "properties": { "url": { "type": "string" }, "price": { "type": "integer" }, "availability": { "type": "string" }, "item_condition": { "type": "string" }, "price_currency": { "type": "string" }, "available_delivery_method": { "type": "string" } } }, "review": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "author": { "type": "object", "properties": { "name": { "type": "string" } } }, "review_body": { "type": "string" }, "review_rating": { "type": "object", "properties": { "best_rating": { "type": "integer" }, "rating_value": { "type": "integer" }, "worst_rating": { "type": "integer" } } }, "date_published": { "type": "string" } } } }, "aggregate_rating": { "type": "object", "properties": { "best_rating": { "type": "integer" }, "rating_value": { "type": "number" }, "review_count": { "type": "integer" } } }, "description": { "type": "string" } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # Website Crawler **GET** `https://api.piloterr.com/v2/website/crawler` A robust solution for efficiently extracting a wide range of data from web pages via high-performance request-mode crawling. **Credit cost:** 1 credit per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | A website URL to crawl. Must include the `http://` or `https://` protocol. **Example:** https://example.com **Notes:** - Only public pages are accessible. Pages behind authentication will not return useful content. - For pages requiring JavaScript rendering, use the [Website Rendering](https://docs.piloterr.com/website-rendering) or [Website WebUnlocker](https://docs.piloterr.com/website-webunlocker) endpoint instead. - Choosing the right API can be tricky this guide will point you to the best option: [Website Scraping](https://www.piloterr.com/blog/website-crawler-vs-rendering-vs-webunlocker) | | `allow_redirects` | query | `boolean` | No | Controls whether the crawler should follow HTTP redirects. - `true`: Follow redirects automatically (**default**) - `false`: Stop at the first HTTP response without following any redirect **Notes:** - **Set to `false`** when you need to inspect the redirect chain itself (e.g. detecting 301 vs 302 codes). | | `return_page_source` | query | `boolean` | No | Controls whether the response returns the raw, unprocessed HTML source of the page. - `false`: Return processed/parsed content (**default**) - `true`: Return the exact HTML source as delivered by the web server **Notes:** - Useful for debugging or when you need the precise markup before any transformation. | ## Responses ### 200 Successful response ```json { "type": "string" } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # Website Email Phone Extractor **GET** `https://api.piloterr.com/v2/website/email_phone_extractor` Extract emails and phone numbers from websites for comprehensive contact details, including social media profiles across 12+ platforms. **Credit cost:** 1 credit per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | A website URL to crawl for contact information. Must include the `http://` or `https://` protocol. The crawler will follow internal links ("a" anchors) to find contact details across the site. **Example:** https://www.hexa.cc **Notes:** - **GDPR:** Results may contain personal data. Ensure you have a legitimate reason for collection under applicable regulations. | | `country_code` | query | `string` | No | An ISO 3166-1 alpha-2 country code used to improve the accuracy of phone number validation and parsing. - `FR`: France - `US`: United States - `DE`: Germany - `GB`: United Kingdom - (any valid ISO country code) **Notes:** - Without a country code, phone numbers may not be validated accurately across different regional formats. - **Recommended** when the target site is country-specific. **Example:** country_code=FR | ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "emails": { "type": "array", "items": { "type": "string" } }, "contact_pages": { "type": "array", "items": {} }, "phone_numbers": { "type": "array", "items": {} }, "reddit_profiles": { "type": "array", "items": {} }, "tiktok_profiles": { "type": "array", "items": {} }, "twitter_profiles": { "type": "array", "items": { "type": "string" } }, "youtube_channels": { "type": "array", "items": {} }, "facebook_profiles": { "type": "array", "items": {} }, "linkedin_profiles": { "type": "array", "items": { "type": "string" } }, "snapchat_profiles": { "type": "array", "items": {} }, "telegram_channels": { "type": "array", "items": {} }, "instagram_profiles": { "type": "array", "items": { "type": "string" } }, "pinterest_profiles": { "type": "array", "items": {} }, "crunchbase_profiles": { "type": "array", "items": {} } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # Website Rendering **GET** `https://api.piloterr.com/v2/website/rendering` High-performance browser-based rendering API to scrape any JavaScript-heavy website, bypassing Cloudflare, Akamai, PerimeterX, and DataDome. **Credit cost:** 2 credits per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | A website URL to render using a headless browser. Must include the `http` or `https` protocol. **Example:** https://example.com **Notes:** - For security and ethical reasons, Piloterr applies domain filtering. Contact support to whitelist your target domain if needed. - Use this endpoint for JavaScript-heavy pages that require client-side rendering. | | `wait_in_seconds` | query | `number` | No | Number of seconds to wait after page load before returning the rendered HTML. Useful for pages with delayed rendering or animations. **Notes:** - Increasing this value adds latency to every request. Use only when a page's content loads after a delay. | | `wait_for` | query | `string` | No | A CSS or XPath selector to wait for before returning the rendered HTML. The headless browser will hold the response until the specified element appears in the DOM. Supported selector types: - **ID selector:** `#loading-container` - **Class selector:** `.content-loaded` - **Combined selector:** `div.main-content#user-profile` **Example:** wait_for=#loading-container **Notes:** - If the element never appears, the request will time out according to the `timeout` parameter. | | `block_ads` | query | `boolean` | No | Controls whether the headless browser should block ad requests during rendering. - `false`: Ads are loaded normally (**default**) - `true`: Ad network requests are blocked, resulting in cleaner HTML and faster rendering **Notes:** - Blocking ads can speed up rendering on ad-heavy pages and reduce noise in the extracted HTML. | | `timeout` | query | `number` | No | Maximum number of seconds to wait for the page to fully load before returning whatever has been rendered so far. - Accepts integer values representing seconds **Notes:** - Setting a lower timeout may result in incomplete HTML for slow-loading pages. - Combine with `wait_for` to ensure critical elements are present before the timeout fires. | ## Responses ### 200 Successful response ```json { "type": "string" } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # Website Screenshot **GET** `https://api.piloterr.com/v2/website/screenshot` Browser-like Screenshot API that captures webpages as PNG/JPEG/WebP or PDF for previews, QA, reporting, monitoring, and archiving no headless setup. **Credit cost:** 2 credits per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `url` | query | `string` | Yes | The URL of the webpage to capture. Examples: - `https://www.amazon.com/s?k=pokemon` - `https://www.cdiscount.com/sante-mieux-vivre/materiel-medical/soin-domicile/l-1650608.html` - `https://github.com/seaweedfs/seaweedfs` | | `format` | query | `string` (`jpeg`, `jpg`, `pdf`, `png`, `webp`) | No | The output format of the screenshot. Available formats: - `webp` - `jpeg` - `jpg` - `png` - `pdf` | | `device` | query | `string` (`galaxy_fold4`, `galaxy_s23`, `galaxy_s23_ultra`, `galaxy_s8`, `huawei_mate_50_pro`, `huawei_p60_pro`, `ipad`, `iphone_12`, `iphone_13_mini`, `iphone_13_pro_max`, `iphone_14_pro`, `iphone_14_pro_max`, `iphone_x`, `pixel_5`, `pixel_6a`, `pixel_7_pro`, `redmi_note_11`, `redmi_note_12_pro`) | No | The device type to emulate for the screenshot. Available devices: - `iphone_14_pro_max` - `iphone_14_pro` - `iphone_13_pro_max` - `iphone_13_mini` - `iphone_12` - `iphone_x` - `ipad` - `galaxy_s23_ultra` - `galaxy_s23` - `galaxy_s8` - `galaxy_fold4` - `pixel_7_pro` - `pixel_6a` - `pixel_5` - `redmi_note_12_pro` - `redmi_note_11` - `huawei_p60_pro` - `huawei_mate_50_pro` | | `full_page` | query | `boolean` | No | Capture the entire page instead of just the visible viewport. | | `full_page_scroll` | query | `boolean` | No | Scroll the page to fully load lazy-loaded elements before capturing a full-page screenshot. | | `full_page_scroll_duration` | query | `number` | No | Time in milliseconds for scrolling before capturing the full page. | | `viewport_width` | query | `number` | No | The width of the browser viewport in pixels. | | `viewport_height` | query | `number` | No | The height of the browser viewport in pixels. | | `scale_factor` | query | `number` | No | The scale factor for high-resolution screenshots. | | `image_quality` | query | `string` | No | Generate images with custom quality settings. Supported formats include: - `jpeg` - `webp` | | `selector` | query | `string` | No | Capture a specific element on the page instead of the full viewport. | | `cache` | query | `boolean` | No | Cache the response. | | `cache_ttl` | query | `number` | No | Cache the response for a custom TTL (in seconds). | | `remove_selectors` | query | `string` | No | A comma-separated list of elements to hide before capturing (e.g., ads, popups). | | `remove_cookie_banners` | query | `boolean` | No | Automatically remove cookie banners before capturing. | | `remove_ads` | query | `boolean` | No | Automatically remove ads before capturing. | | `block_resources` | query | `string` (`document`, `eventsource`, `fetch`, `font`, `image`, `manifest`, `media`, `other`, `script`, `stylesheet`, `texttrack`, `websocket`, `xhr`) | No | Comma-separated list of resource types to block (e.g., “image,stylesheet,font”). Available resource types: - `document` - `stylesheet` - `image` - `media` - `font` - `script` - `texttrack` - `xhr` - `fetch` - `eventsource` - `websocket` - `manifest` - `other` Useful for optimizing page loading speed before capturing screenshots. | | `block_urls` | query | `string` | No | Comma-separated list of URL patterns to block (e.g., “analytics,tracking,advertisement”). You can specify URLs, domains, or simple patterns like “.example.com/”. | | `delay` | query | `number` | No | Delay in seconds before capturing the screenshot. | | `wait_until` | query | `array` (`domcontentloaded`, `load`, `networkidle0`, `networkidle2`) | No | Define when to capture. Available formats: - `networkidle2` - `load` - `domcontentloaded` - `networkidle0` | | `wait_for_selector` | query | `string` | No | Wait for a specific element to appear before taking the screenshot. | | `proxy` | query | `string` | No | Specify a proxy server to route your request through. Supports `HTTP`, `HTTPS`, and `SOCKS5` proxies. Format: http://username:password@proxy.com:PORT. Useful for bypassing geo-restrictions and rotating IPs. | | `s3_secret_key` | query | `string` | No | AWS S3 secret access key. | | `s3_access_key_id` | query | `string` | No | AWS S3 access key ID. | | `s3_bucket` | query | `string` | No | The S3 bucket name where the screenshot will be uploaded. | | `s3_object_key` | query | `string` | No | The filename for the S3 object (auto-generated if not provided). | | `s3_region` | query | `string` | No | AWS S3 region for storage. | | `storage_endpoint` | query | `string` | No | Leave this field empty for AWS S3. Only specify a value if required. S3-compatible storage services are supported, for example, use https://.r2.cloudflarestorage.com for Cloudflare R2. | | `s3_url` | query | `boolean` | No | Use S3 storage for screenshots. The S3 URL will be returned in the response. | ## Responses ### 200 Successful response ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # Website Technology **GET** `https://api.piloterr.com/v2/website/technology` Identify the technologies behind any website CMS, frameworks, analytics, CDN, hosting, and more — for competitive market analysis and technological insight. **Credit cost:** 1 credit per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | A website URL to analyze for technology stack detection. Must include the `http://` or `https://` protocol. **Example:** https://example.com **Notes:** - Response time is typically between 10 and 15 seconds due to deep technology fingerprinting. - Works with any public-facing website URL. | | `mode` | query | `string` | No | Controls the level of detail returned in the technology detection response. - `expert`: Returns comprehensive technical details including confidence scores, version numbers, CPE identifiers, category metadata, and technology descriptions. **Default.** - `simple`: Returns a lightweight summary with the CMS name, URL status codes, and a flat list of technology names **Notes:** - Use `simple` mode for quick stack overviews or when building dashboards that only need technology names. - Use `expert` mode when you need confidence scores, categorization, or version information for deep analysis. | ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "cms": { "type": "string" }, "urls": { "type": "object", "properties": { "https://piloterr.com/": { "type": "object", "properties": { "status": { "type": "integer" } } }, "https://www.piloterr.com/": { "type": "object", "properties": { "status": { "type": "integer" } } } } }, "technologies": { "type": "array", "items": { "type": "string" } } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # Website WebUnlocker **GET** `https://api.piloterr.com/v2/website/webunlocker` WebUnlocker is a hybrid of realistic JS rendering and request-mode crawling, engineered to bypass advanced anti-bot systems on whitelisted websites. **Credit cost:** 3 credits per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | A website URL to unlock using the WebUnlocker engine. Must include the `http` or `https` protocol. The target domain must be on Piloterr's approved whitelist. **Example:** https://www.norauto.fr/t/pneu/w-185-h-55-r-14/ete-s/80-l-h-q.html Examples of supported domains: `mobile.de`, `leroymerlin.fr`, `norauto.fr` **Notes:** - **Beta endpoint:** Features and functionality may change as the service is improved. - **Whitelist required:** Contact Piloterr support to request adding a new domain to the authorized list before use. - Choosing the right API can be tricky this guide will point you to the best option: [Website Scraping](https://www.piloterr.com/blog/website-crawler-vs-rendering-vs-webunlocker) | | `allow_redirects` | query | `boolean` | No | Controls whether the WebUnlocker engine should follow HTTP redirects. - `true`: Follow redirects automatically (**default**) - `false`: Stop at the first HTTP response without following any redirect **Notes:** - **Set to `false`** when you need to inspect the redirect chain or capture intermediate responses. | | `return_page_source` | query | `boolean` | No | Controls whether the response returns the raw, unprocessed HTML source of the page. - `false`: Return processed/parsed content (**default**) - `true`: Return the exact HTML source as delivered by the web server after bot bypass **Notes:** - Useful when you need the unmodified server response for debugging or precise parsing. | ## Responses ### 200 Successful response ```json { "type": "string" } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # Weibo Post Info **GET** `https://api.piloterr.com/v2/weibo/post/info` Retrieve detailed information from any Weibo post, including post text, images, user profile data, and engagement metrics. **Status:** Degraded **Credit cost:** 1 credit per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | A Weibo post URL or post ID. **Examples:** https://m.weibo.cn/detail/5062595839264600 Both the full Weibo mobile URL and the numeric post ID are accepted. | ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "post": { "type": "object", "properties": { "id": { "type": "string" }, "text": { "type": "string" }, "pics": { "type": "array", "items": { "type": "object", "properties": { "pid": { "type": "string" }, "url": { "type": "string" }, "large": { "type": "object", "properties": { "url": { "type": "string" } } } } } }, "user": { "type": "object", "properties": { "id": { "type": "integer" }, "svip": { "type": "integer" }, "enterprise": { "type": "integer" }, "screen_name": { "type": "string" }, "followers_count": { "type": "string" }, "verified": { "type": "boolean" } } } } } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # Weibo Search **GET** `https://api.piloterr.com/v2/weibo/search` Search Weibo using a mobile search URL to retrieve posts, users, and content matching a keyword or hashtag. **Status:** Degraded **Credit cost:** 1 credit per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | A Weibo search URL. **Example:** https://m.weibo.cn/search?containerid=231522type%3D1%26t%3D10%26q%3D%23%E8%B0%A2%E8%B0%A2%E4%BD%A0%E4%BB%AC%23 Generate search URLs from the Weibo mobile search interface (m.weibo.cn) and copy the URL. | | `page` | query | `number` | No | Page number for paginating through search results. **Note:** Increment the page number to retrieve subsequent pages of results. | ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "response": { "type": "array", "items": { "type": "object", "properties": { "card_type": { "type": "integer" }, "show_type": { "type": "integer" }, "card_group": { "type": "array", "items": { "type": "object", "properties": { "users": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "gender": { "type": "string" }, "screen_name": { "type": "string" }, "verified": { "type": "boolean" }, "follow_count": { "type": "integer" }, "statuses_count": { "type": "integer" }, "followers_count": { "type": "string" }, "profile_url": { "type": "string" }, "profile_image_url": { "type": "string" } } } } } } } } } } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # Wellfound Company Info **GET** `https://api.piloterr.com/v2/wellfound/company/info` Retrieve startup and company data from Wellfound (formerly AngelList), including description, funding, team size, hiring status, and social links. **Status:** Degraded **Credit cost:** 1 credit per call ## Authentication Pass your API key as a header: ``` x-api-key: YOUR_API_KEY ``` ## Parameters | Name | In | Type | Required | Description | |------|----|------|:--------:|-------------| | `query` | query | `string` | Yes | A Wellfound company URL or company slug. **Examples:** https://wellfound.com/company/dataiku Both the full Wellfound URL and the company slug are accepted. | ## Responses ### 200 Successful response ```json { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "logo": { "type": "string" }, "slug": { "type": "string" }, "headline": { "type": "string" }, "description": { "type": "string" }, "is_operating": { "nullable": true }, "is_incubator": { "type": "boolean" }, "hiring": { "type": "boolean" }, "employee_count": { "type": "string" }, "website": { "type": "string" }, "social_networks": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "url": { "type": "string" } } } }, "company_financials_highlights": { "type": "object", "properties": { "funding_total": { "type": "integer" }, "num_funding_rounds": { "type": "integer" } } } } } ``` ### 400 Bad Request — missing or invalid parameters. ```json { "error": "Bad Request" } ``` ### 401 Unauthorized — the API key is missing, invalid, inactive, or expired. ```json { "error": "Invalid API Key" } ``` ### 402 Payment Required — your subscription or credit balance is insufficient. ```json { "error": "Payment required" } ``` ### 429 Too Many Requests — you exceeded your rate limit quota. ```json { "error": "Rate limit exceeded for the API key: quota monthly" } ``` ### 500 Internal Server Error — something went wrong on our side. ```json { "error": "Internal Error" } ``` # Collect Google Images Overview [#overview] This playbook shows how to collect image URLs, titles, and dimensions from Google Images for a given query. Each result includes the direct image URL, the page it was found on, its source domain, and pixel dimensions. Prerequisites [#prerequisites] * An Autom API key — get one at [app.autom.dev](https://app.autom.dev) * Install dependencies for your language: ```bash pip install requests ``` No extra dependencies — uses the native `fetch` API (Node 18+). `curl` extension enabled (on by default in most PHP installs). No extra dependencies — uses `net/http` (Go 1.18+). No extra dependencies — uses `java.net.http` (Java 11+). No extra dependencies — uses `System.Net.Http` (.NET 6+). ```toml # Cargo.toml [dependencies] reqwest = { version = "0.12", features = ["json"] } tokio = { version = "1", features = ["full"] } serde_json = "1" ``` Steps [#steps] Search for images [#search-for-images] Call `GET /v1/google/images` with a `q` parameter. ```python import requests API_KEY = "YOUR_API_KEY" response = requests.get( "https://api.autom.dev/v1/google/images", headers={"x-api-key": API_KEY}, params={"q": "electric car charging station", "gl": "us", "hl": "en"}, ) data = response.json() ``` ```typescript const API_KEY = "YOUR_API_KEY"; const params = new URLSearchParams({ q: "electric car charging station", gl: "us", hl: "en" }); const response = await fetch(`https://api.autom.dev/v1/google/images?${params}`, { headers: { "x-api-key": API_KEY }, }); const data = await response.json(); ``` ```php "electric car charging station", "gl" => "us", "hl" => "en"]); $ch = curl_init("https://api.autom.dev/v1/google/images?{$params}"); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_HTTPHEADER, ["x-api-key: {$apiKey}"]); $data = json_decode(curl_exec($ch), true); curl_close($ch); ``` ```go package main import ( "encoding/json" "io" "net/http" "net/url" ) func main() { params := url.Values{"q": {"electric car charging station"}, "gl": {"us"}, "hl": {"en"}} req, _ := http.NewRequest("GET", "https://api.autom.dev/v1/google/images?"+params.Encode(), nil) req.Header.Set("x-api-key", "YOUR_API_KEY") resp, _ := http.DefaultClient.Do(req) defer resp.Body.Close() body, _ := io.ReadAll(resp.Body) var data map[string]any json.Unmarshal(body, &data) } ``` ```java import java.net.URI; import java.net.http.*; var client = HttpClient.newHttpClient(); var request = HttpRequest.newBuilder() .uri(URI.create("https://api.autom.dev/v1/google/images?q=electric+car+charging+station&gl=us&hl=en")) .header("x-api-key", "YOUR_API_KEY") .GET().build(); var response = client.send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.body()); ``` ```csharp using System.Net.Http; using var client = new HttpClient(); client.DefaultRequestHeaders.Add("x-api-key", "YOUR_API_KEY"); var body = await client.GetStringAsync( "https://api.autom.dev/v1/google/images?q=electric+car+charging+station&gl=us&hl=en"); ``` ```rust #[tokio::main] async fn main() -> Result<(), reqwest::Error> { let data = reqwest::Client::new() .get("https://api.autom.dev/v1/google/images") .header("x-api-key", "YOUR_API_KEY") .query(&[("q", "electric car charging station"), ("gl", "us"), ("hl", "en")]) .send().await?.json::().await?; println!("{:#?}", data); Ok(()) } ``` Inspect the image results [#inspect-the-image-results] Each item in `images` has `url` (direct image), `link` (source page), `title`, `domain`, `source`, `image_width`, and `image_height`. ```python for img in data.get("images", []): print(f"[{img['position']}] {img['title']}") print(f" Image : {img['url']}") print(f" Source: {img['source']} — {img['image_width']}x{img['image_height']}px\n") ``` ```typescript for (const img of data.images ?? []) { console.log(`[${img.position}] ${img.title}`); console.log(` Image : ${img.url}`); console.log(` Source: ${img.source} — ${img.image_width}x${img.image_height}px\n`); } ``` ```php foreach ($data["images"] ?? [] as $img) { echo "[{$img['position']}] {$img['title']}\n"; echo " Image : {$img['url']}\n"; echo " Source: {$img['source']} — {$img['image_width']}x{$img['image_height']}px\n\n"; } ``` ```go import "fmt" for _, r := range data["images"].([]any) { img := r.(map[string]any) fmt.Printf("[%.0f] %s\n Image : %s\n Source: %s — %.0fx%.0fpx\n\n", img["position"], img["title"], img["url"], img["source"], img["image_width"], img["image_height"]) } ``` ```java import org.json.*; var images = new JSONObject(response.body()).getJSONArray("images"); for (int i = 0; i < images.length(); i++) { var img = images.getJSONObject(i); System.out.printf("[%d] %s%n Image : %s%n Source: %s — %dx%dpx%n%n", img.getInt("position"), img.getString("title"), img.getString("url"), img.getString("source"), img.getInt("image_width"), img.getInt("image_height")); } ``` ```csharp using System.Text.Json; var images = JsonDocument.Parse(body).RootElement.GetProperty("images").EnumerateArray(); foreach (var img in images) { Console.WriteLine($"[{img.GetProperty("position")}] {img.GetProperty("title")}"); Console.WriteLine($" Image : {img.GetProperty("url")}"); Console.WriteLine($" Source: {img.GetProperty("source")} — {img.GetProperty("image_width")}x{img.GetProperty("image_height")}px\n"); } ``` ```rust if let Some(images) = data["images"].as_array() { for img in images { println!("[{}] {}", img["position"], img["title"].as_str().unwrap_or("")); println!(" Image : {}", img["url"].as_str().unwrap_or("")); println!(" Source: {} — {}x{}px\n", img["source"].as_str().unwrap_or(""), img["image_width"], img["image_height"]); } } ``` Build an image catalog filtered by minimum size [#build-an-image-catalog-filtered-by-minimum-size] Filter out thumbnails and save only high-resolution images. ```python import csv, requests API_KEY = "YOUR_API_KEY" QUERY = "electric car charging station" MIN_WIDTH = 800 def fetch_images(query: str, pages: int = 2) -> list: results = [] for page in range(1, pages + 1): r = requests.get("https://api.autom.dev/v1/google/images", headers={"x-api-key": API_KEY}, params={"q": query, "gl": "us", "hl": "en", "page": page}) results.extend(r.json().get("images", [])) return results large = [img for img in fetch_images(QUERY) if img.get("image_width", 0) >= MIN_WIDTH] with open("image_catalog.csv", "w", newline="") as f: writer = csv.DictWriter(f, fieldnames=["position", "title", "url", "source", "image_width", "image_height"]) writer.writeheader() writer.writerows(large) print(f"Saved {len(large)} high-res images to image_catalog.csv") ``` ```typescript import { writeFileSync } from "fs"; const API_KEY = "YOUR_API_KEY"; const MIN_WIDTH = 800; async function fetchImages(query: string, pages = 2): Promise { const all: any[] = []; for (let page = 1; page <= pages; page++) { const params = new URLSearchParams({ q: query, gl: "us", hl: "en", page: String(page) }); const res = await fetch(`https://api.autom.dev/v1/google/images?${params}`, { headers: { "x-api-key": API_KEY }, }); all.push(...((await res.json()).images ?? [])); } return all; } const images = await fetchImages("electric car charging station"); const large = images.filter(img => (img.image_width ?? 0) >= MIN_WIDTH); writeFileSync("image_catalog.json", JSON.stringify(large, null, 2)); console.log(`Saved ${large.length} high-res images to image_catalog.json`); ``` ```php $query, "gl" => "us", "hl" => "en", "page" => $page]); $ch = curl_init("https://api.autom.dev/v1/google/images?{$params}"); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_HTTPHEADER, ["x-api-key: {$apiKey}"]); $data = json_decode(curl_exec($ch), true); curl_close($ch); $all = array_merge($all, $data["images"] ?? []); } return $all; } $large = array_filter(fetchImages($apiKey, $query), fn($img) => ($img["image_width"] ?? 0) >= $minWidth); file_put_contents("image_catalog.json", json_encode(array_values($large), JSON_PRETTY_PRINT)); echo "Saved " . count($large) . " high-res images to image_catalog.json\n"; ``` ```go package main import ( "encoding/json" "fmt" "io" "net/http" "net/url" "os" "strconv" ) func fetchImages(apiKey, query string, pages int) []map[string]any { var all []map[string]any for page := 1; page <= pages; page++ { params := url.Values{"q": {query}, "gl": {"us"}, "hl": {"en"}, "page": {strconv.Itoa(page)}} req, _ := http.NewRequest("GET", "https://api.autom.dev/v1/google/images?"+params.Encode(), nil) req.Header.Set("x-api-key", apiKey) resp, _ := http.DefaultClient.Do(req) body, _ := io.ReadAll(resp.Body) resp.Body.Close() var data map[string]any json.Unmarshal(body, &data) for _, r := range data["images"].([]any) { all = append(all, r.(map[string]any)) } } return all } func main() { images := fetchImages("YOUR_API_KEY", "electric car charging station", 2) minWidth := float64(800) var large []map[string]any for _, img := range images { if img["image_width"].(float64) >= minWidth { large = append(large, img) } } b, _ := json.MarshalIndent(large, "", " ") os.WriteFile("image_catalog.json", b, 0644) fmt.Printf("Saved %d high-res images to image_catalog.json\n", len(large)) } ``` ```java import java.net.URI; import java.net.URLEncoder; import java.net.http.*; import java.nio.charset.StandardCharsets; import java.nio.file.*; import java.util.*; import org.json.*; public class Main { public static void main(String[] args) throws Exception { var apiKey = "YOUR_API_KEY"; var query = URLEncoder.encode("electric car charging station", StandardCharsets.UTF_8); var minWidth = 800; var client = HttpClient.newHttpClient(); var all = new JSONArray(); for (int page = 1; page <= 2; page++) { var url = "https://api.autom.dev/v1/google/images?q=" + query + "&gl=us&hl=en&page=" + page; var req = HttpRequest.newBuilder().uri(URI.create(url)) .header("x-api-key", apiKey).GET().build(); var resp = client.send(req, HttpResponse.BodyHandlers.ofString()); var imgs = new JSONObject(resp.body()).getJSONArray("images"); for (int i = 0; i < imgs.length(); i++) all.put(imgs.get(i)); } var large = new JSONArray(); for (int i = 0; i < all.length(); i++) { var img = all.getJSONObject(i); if (img.getInt("image_width") >= minWidth) large.put(img); } Files.writeString(Path.of("image_catalog.json"), large.toString(2)); System.out.println("Saved " + large.length() + " high-res images to image_catalog.json"); } } ``` ```csharp using System.Net.Http; using System.Text.Json; var apiKey = "YOUR_API_KEY"; var minWidth = 800; using var client = new HttpClient(); client.DefaultRequestHeaders.Add("x-api-key", apiKey); var all = new List(); for (int page = 1; page <= 2; page++) { var body = await client.GetStringAsync( $"https://api.autom.dev/v1/google/images?q=electric+car+charging+station&gl=us&hl=en&page={page}"); var json = JsonDocument.Parse(body).RootElement; foreach (var img in json.GetProperty("images").EnumerateArray()) all.Add(img); } var large = all.Where(img => img.GetProperty("image_width").GetInt32() >= minWidth).ToList(); File.WriteAllText("image_catalog.json", JsonSerializer.Serialize(large, new JsonSerializerOptions { WriteIndented = true })); Console.WriteLine($"Saved {large.Count} high-res images to image_catalog.json"); ``` ```rust use reqwest::Client; use serde_json::Value; use std::fs; async fn fetch_images(client: &Client, api_key: &str, query: &str, pages: u32) -> Vec { let mut all = Vec::new(); for page in 1..=pages { let data = client.get("https://api.autom.dev/v1/google/images") .header("x-api-key", api_key) .query(&[("q", query), ("gl", "us"), ("hl", "en"), ("page", &page.to_string())]) .send().await.unwrap().json::().await.unwrap(); if let Some(imgs) = data["images"].as_array() { all.extend(imgs.clone()); } } all } #[tokio::main] async fn main() -> Result<(), reqwest::Error> { let client = Client::new(); let images = fetch_images(&client, "YOUR_API_KEY", "electric car charging station", 2).await; let large: Vec<&Value> = images.iter() .filter(|img| img["image_width"].as_i64().unwrap_or(0) >= 800) .collect(); fs::write("image_catalog.json", serde_json::to_string_pretty(&large).unwrap()).unwrap(); println!("Saved {} high-res images to image_catalog.json", large.len()); Ok(()) } ``` The `url` field in each result is the direct link to the image file. Always verify you have the rights to use an image before including it in a dataset or product. # Monitor Google News Overview [#overview] This playbook builds a **news monitoring pipeline**: query Google News for a brand name, product, or topic and collect all article titles, sources, and publication dates. Run it on a cron schedule to detect press coverage as soon as it appears. Prerequisites [#prerequisites] * An Autom API key — get one at [app.autom.dev](https://app.autom.dev) * Install dependencies for your language: ```bash pip install requests ``` No extra dependencies — uses the native `fetch` API (Node 18+). `curl` extension enabled (on by default in most PHP installs). No extra dependencies — uses the `net/http` standard library (Go 1.18+). No extra dependencies — uses `java.net.http` (Java 11+). No extra dependencies — uses `System.Net.Http` (.NET 6+). ```toml # Cargo.toml [dependencies] reqwest = { version = "0.12", features = ["json"] } tokio = { version = "1", features = ["full"] } serde_json = "1" ``` Steps [#steps] Fetch latest news articles [#fetch-latest-news-articles] Call `GET /v1/google/news` with the keyword you want to monitor. ```python import requests API_KEY = "YOUR_API_KEY" response = requests.get( "https://api.autom.dev/v1/google/news", headers={"x-api-key": API_KEY}, params={"q": "OpenAI", "gl": "us", "hl": "en"}, ) data = response.json() ``` ```typescript const API_KEY = "YOUR_API_KEY"; const params = new URLSearchParams({ q: "OpenAI", gl: "us", hl: "en" }); const response = await fetch(`https://api.autom.dev/v1/google/news?${params}`, { headers: { "x-api-key": API_KEY }, }); const data = await response.json(); ``` ```php "OpenAI", "gl" => "us", "hl" => "en"]); $ch = curl_init("https://api.autom.dev/v1/google/news?{$params}"); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_HTTPHEADER, ["x-api-key: {$apiKey}"]); $data = json_decode(curl_exec($ch), true); curl_close($ch); ``` ```go package main import ( "encoding/json" "io" "net/http" "net/url" ) func main() { params := url.Values{"q": {"OpenAI"}, "gl": {"us"}, "hl": {"en"}} req, _ := http.NewRequest("GET", "https://api.autom.dev/v1/google/news?"+params.Encode(), nil) req.Header.Set("x-api-key", "YOUR_API_KEY") resp, _ := http.DefaultClient.Do(req) defer resp.Body.Close() body, _ := io.ReadAll(resp.Body) var data map[string]any json.Unmarshal(body, &data) // use data below } ``` ```java import java.net.URI; import java.net.http.*; var client = HttpClient.newHttpClient(); var request = HttpRequest.newBuilder() .uri(URI.create("https://api.autom.dev/v1/google/news?q=OpenAI&gl=us&hl=en")) .header("x-api-key", "YOUR_API_KEY") .GET().build(); var response = client.send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.body()); ``` ```csharp using System.Net.Http; using var client = new HttpClient(); client.DefaultRequestHeaders.Add("x-api-key", "YOUR_API_KEY"); var body = await client.GetStringAsync( "https://api.autom.dev/v1/google/news?q=OpenAI&gl=us&hl=en"); Console.WriteLine(body); ``` ```rust #[tokio::main] async fn main() -> Result<(), reqwest::Error> { let data = reqwest::Client::new() .get("https://api.autom.dev/v1/google/news") .header("x-api-key", "YOUR_API_KEY") .query(&[("q", "OpenAI"), ("gl", "us"), ("hl", "en")]) .send().await? .json::().await?; println!("{:#?}", data); Ok(()) } ``` Extract and display articles [#extract-and-display-articles] Each item in `organic_results` has `title`, `link`, `source`, `date`, and `snippet`. ```python for article in data.get("organic_results", []): print(f"[{article['date']}] {article['title']}") print(f" Source : {article['source']}") print(f" URL : {article['link']}\n") ``` ```typescript for (const article of data.organic_results ?? []) { console.log(`[${article.date}] ${article.title}`); console.log(` Source : ${article.source}`); console.log(` URL : ${article.link}\n`); } ``` ```php foreach ($data["organic_results"] ?? [] as $article) { echo "[{$article['date']}] {$article['title']}\n"; echo " Source : {$article['source']}\n"; echo " URL : {$article['link']}\n\n"; } ``` ```go results := data["organic_results"].([]any) for _, r := range results { a := r.(map[string]any) fmt.Printf("[%s] %s\n Source : %s\n URL : %s\n\n", a["date"], a["title"], a["source"], a["link"]) } ``` ```java import org.json.*; var json = new JSONObject(response.body()); var results = json.getJSONArray("organic_results"); for (int i = 0; i < results.length(); i++) { var a = results.getJSONObject(i); System.out.printf("[%s] %s%n Source : %s%n URL : %s%n%n", a.getString("date"), a.getString("title"), a.getString("source"), a.getString("link")); } ``` ```csharp using System.Text.Json; var json = JsonDocument.Parse(body); var results = json.RootElement.GetProperty("organic_results").EnumerateArray(); foreach (var a in results) { Console.WriteLine($"[{a.GetProperty("date")}] {a.GetProperty("title")}"); Console.WriteLine($" Source : {a.GetProperty("source")}"); Console.WriteLine($" URL : {a.GetProperty("link")}\n"); } ``` ```rust if let Some(articles) = data["organic_results"].as_array() { for a in articles { println!("[{}] {}", a["date"].as_str().unwrap_or(""), a["title"].as_str().unwrap_or("")); println!(" Source : {}", a["source"].as_str().unwrap_or("")); println!(" URL : {}\n", a["link"].as_str().unwrap_or("")); } } ``` Build a monitoring pipeline with deduplication [#build-a-monitoring-pipeline-with-deduplication] Store seen article URLs so repeated runs don't produce duplicate alerts. ```python import json, requests from pathlib import Path API_KEY = "YOUR_API_KEY" KEYWORDS = ["OpenAI", "Anthropic", "Mistral AI"] SEEN_FILE = Path("seen_articles.json") def load_seen() -> set: return set(json.loads(SEEN_FILE.read_text())) if SEEN_FILE.exists() else set() def save_seen(seen: set) -> None: SEEN_FILE.write_text(json.dumps(list(seen))) def fetch_news(query: str) -> list: r = requests.get("https://api.autom.dev/v1/google/news", headers={"x-api-key": API_KEY}, params={"q": query, "gl": "us", "hl": "en"}) return r.json().get("organic_results", []) seen = load_seen() new_articles = [] for keyword in KEYWORDS: for article in fetch_news(keyword): if article["link"] not in seen: seen.add(article["link"]) new_articles.append({**article, "keyword": keyword}) save_seen(seen) print(f"Found {len(new_articles)} new article(s):") for a in new_articles: print(f" [{a['keyword']}] {a['title']} — {a['source']}") ``` ```typescript import { readFileSync, writeFileSync, existsSync } from "fs"; const API_KEY = "YOUR_API_KEY"; const KEYWORDS = ["OpenAI", "Anthropic", "Mistral AI"]; const SEEN_FILE = "seen_articles.json"; function loadSeen(): Set { return existsSync(SEEN_FILE) ? new Set(JSON.parse(readFileSync(SEEN_FILE, "utf-8"))) : new Set(); } async function fetchNews(query: string): Promise { const params = new URLSearchParams({ q: query, gl: "us", hl: "en" }); const res = await fetch(`https://api.autom.dev/v1/google/news?${params}`, { headers: { "x-api-key": API_KEY }, }); return (await res.json()).organic_results ?? []; } const seen = loadSeen(); const newArticles: any[] = []; for (const keyword of KEYWORDS) { for (const article of await fetchNews(keyword)) { if (!seen.has(article.link)) { seen.add(article.link); newArticles.push({ ...article, keyword }); } } } writeFileSync(SEEN_FILE, JSON.stringify([...seen])); console.log(`Found ${newArticles.length} new article(s):`); for (const a of newArticles) console.log(` [${a.keyword}] ${a.title} — ${a.source}`); ``` ```php $keyword, "gl" => "us", "hl" => "en"]); $ch = curl_init("https://api.autom.dev/v1/google/news?{$params}"); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_HTTPHEADER, ["x-api-key: {$apiKey}"]); $data = json_decode(curl_exec($ch), true); curl_close($ch); foreach ($data["organic_results"] ?? [] as $article) { if (!isset($seen[$article["link"]])) { $seen[$article["link"]] = true; $newArticles[] = array_merge($article, ["keyword" => $keyword]); } } } file_put_contents($seenFile, json_encode(array_keys($seen))); echo "Found " . count($newArticles) . " new article(s):\n"; foreach ($newArticles as $a) echo " [{$a['keyword']}] {$a['title']} — {$a['source']}\n"; ``` ```go package main import ( "encoding/json" "fmt" "io" "net/http" "net/url" "os" ) func fetchNews(apiKey, query string) []map[string]any { params := url.Values{"q": {query}, "gl": {"us"}, "hl": {"en"}} req, _ := http.NewRequest("GET", "https://api.autom.dev/v1/google/news?"+params.Encode(), nil) req.Header.Set("x-api-key", apiKey) resp, _ := http.DefaultClient.Do(req) defer resp.Body.Close() body, _ := io.ReadAll(resp.Body) var data map[string]any json.Unmarshal(body, &data) var out []map[string]any for _, r := range data["organic_results"].([]any) { out = append(out, r.(map[string]any)) } return out } func main() { apiKey := "YOUR_API_KEY" keywords := []string{"OpenAI", "Anthropic", "Mistral AI"} seen := map[string]bool{} if b, err := os.ReadFile("seen_articles.json"); err == nil { var links []string json.Unmarshal(b, &links) for _, l := range links { seen[l] = true } } var newCount int for _, kw := range keywords { for _, a := range fetchNews(apiKey, kw) { link := a["link"].(string) if !seen[link] { seen[link] = true fmt.Printf(" [%s] %s — %s\n", kw, a["title"], a["source"]) newCount++ } } } links := make([]string, 0, len(seen)) for l := range seen { links = append(links, l) } b, _ := json.Marshal(links) os.WriteFile("seen_articles.json", b, 0644) fmt.Printf("Found %d new article(s).\n", newCount) } ``` ```java import java.net.URI; import java.net.URLEncoder; import java.net.http.*; import java.nio.charset.StandardCharsets; import java.nio.file.*; import java.util.*; import org.json.*; public class Main { static HttpClient client = HttpClient.newHttpClient(); static String API_KEY = "YOUR_API_KEY"; public static void main(String[] args) throws Exception { var keywords = List.of("OpenAI", "Anthropic", "Mistral AI"); var seenPath = Path.of("seen_articles.json"); var seen = new HashSet(); if (Files.exists(seenPath)) { var arr = new JSONArray(Files.readString(seenPath)); for (int i = 0; i < arr.length(); i++) seen.add(arr.getString(i)); } int newCount = 0; for (var kw : keywords) { var q = URLEncoder.encode(kw, StandardCharsets.UTF_8); var url = "https://api.autom.dev/v1/google/news?q=" + q + "&gl=us&hl=en"; var req = HttpRequest.newBuilder().uri(URI.create(url)) .header("x-api-key", API_KEY).GET().build(); var resp = client.send(req, HttpResponse.BodyHandlers.ofString()); var results = new JSONObject(resp.body()).getJSONArray("organic_results"); for (int i = 0; i < results.length(); i++) { var a = results.getJSONObject(i); var link = a.getString("link"); if (!seen.contains(link)) { seen.add(link); System.out.printf(" [%s] %s — %s%n", kw, a.getString("title"), a.getString("source")); newCount++; } } } Files.writeString(seenPath, new JSONArray(seen).toString()); System.out.println("Found " + newCount + " new article(s)."); } } ``` ```csharp using System.Net.Http; using System.Text.Json; var apiKey = "YOUR_API_KEY"; var keywords = new[] { "OpenAI", "Anthropic", "Mistral AI" }; var seenFile = "seen_articles.json"; using var client = new HttpClient(); client.DefaultRequestHeaders.Add("x-api-key", apiKey); var seen = File.Exists(seenFile) ? JsonSerializer.Deserialize>(File.ReadAllText(seenFile))! : new HashSet(); int newCount = 0; foreach (var keyword in keywords) { var url = $"https://api.autom.dev/v1/google/news?q={Uri.EscapeDataString(keyword)}&gl=us&hl=en"; var body = await client.GetStringAsync(url); var json = JsonDocument.Parse(body).RootElement; foreach (var a in json.GetProperty("organic_results").EnumerateArray()) { var link = a.GetProperty("link").GetString()!; if (seen.Add(link)) { Console.WriteLine($" [{keyword}] {a.GetProperty("title")} — {a.GetProperty("source")}"); newCount++; } } } File.WriteAllText(seenFile, JsonSerializer.Serialize(seen)); Console.WriteLine($"Found {newCount} new article(s)."); ``` ```rust use reqwest::Client; use serde_json::Value; use std::{collections::HashSet, fs, path::Path}; async fn fetch_news(client: &Client, api_key: &str, query: &str) -> Vec { let data = client .get("https://api.autom.dev/v1/google/news") .header("x-api-key", api_key) .query(&[("q", query), ("gl", "us"), ("hl", "en")]) .send().await.unwrap().json::().await.unwrap(); data["organic_results"].as_array().cloned().unwrap_or_default() } #[tokio::main] async fn main() -> Result<(), reqwest::Error> { let client = Client::new(); let api_key = "YOUR_API_KEY"; let keywords = ["OpenAI", "Anthropic", "Mistral AI"]; let seen_path = Path::new("seen_articles.json"); let mut seen: HashSet = if seen_path.exists() { serde_json::from_str::>(&fs::read_to_string(seen_path).unwrap()) .unwrap().into_iter().collect() } else { HashSet::new() }; let mut new_count = 0; for keyword in &keywords { for article in fetch_news(&client, api_key, keyword).await { let link = article["link"].as_str().unwrap_or("").to_string(); if seen.insert(link) { println!(" [{}] {} — {}", keyword, article["title"].as_str().unwrap_or(""), article["source"].as_str().unwrap_or("")); new_count += 1; } } } let seen_vec: Vec<&String> = seen.iter().collect(); fs::write(seen_path, serde_json::to_string(&seen_vec).unwrap()).unwrap(); println!("Found {new_count} new article(s)."); Ok(()) } ``` Schedule this script with a cron job (e.g. every hour) or a task scheduler to receive continuous coverage monitoring. Combine multiple keywords in one run to minimize credit usage. # Scrape Google Search Results Overview [#overview] In this playbook you will build a script that queries Google Search and extracts structured organic results — positions, titles, URLs, and snippets — for any keyword. A typical use case is **rank tracking**: run this on a schedule to monitor where your pages appear for target keywords. The endpoint returns up to 10 organic results per page and supports pagination, country (`gl`) and language (`hl`) targeting. Prerequisites [#prerequisites] * An Autom API key — get one at [app.autom.dev](https://app.autom.dev) * Install dependencies for your language: ```bash pip install requests ``` No extra dependencies — uses the native `fetch` API (Node 18+). `curl` extension enabled (on by default in most PHP installs). No extra dependencies — uses the `net/http` standard library (Go 1.18+). No extra dependencies — uses `java.net.http` (Java 11+). No extra dependencies — uses `System.Net.Http` (.NET 6+). ```toml # Cargo.toml [dependencies] reqwest = { version = "0.12", features = ["json"] } tokio = { version = "1", features = ["full"] } serde_json = "1" ``` Steps [#steps] Make your first search request [#make-your-first-search-request] Call `GET /v1/google/search` with the `q` parameter and your API key in the `x-api-key` header. ```python import requests API_KEY = "YOUR_API_KEY" response = requests.get( "https://api.autom.dev/v1/google/search", headers={"x-api-key": API_KEY}, params={"q": "best python web scraping libraries", "gl": "us", "hl": "en"}, ) data = response.json() print(data) ``` ```typescript const API_KEY = "YOUR_API_KEY"; const params = new URLSearchParams({ q: "best python web scraping libraries", gl: "us", hl: "en", }); const response = await fetch( `https://api.autom.dev/v1/google/search?${params}`, { headers: { "x-api-key": API_KEY } }, ); const data = await response.json(); console.log(data); ``` ```php "best python web scraping libraries", "gl" => "us", "hl" => "en", ]); $ch = curl_init("https://api.autom.dev/v1/google/search?{$params}"); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_HTTPHEADER, ["x-api-key: {$apiKey}"]); $data = json_decode(curl_exec($ch), true); curl_close($ch); print_r($data); ``` ```go package main import ( "encoding/json" "fmt" "io" "net/http" "net/url" ) func main() { apiKey := "YOUR_API_KEY" params := url.Values{} params.Set("q", "best python web scraping libraries") params.Set("gl", "us") params.Set("hl", "en") req, _ := http.NewRequest("GET", "https://api.autom.dev/v1/google/search?"+params.Encode(), nil) req.Header.Set("x-api-key", apiKey) resp, _ := http.DefaultClient.Do(req) defer resp.Body.Close() body, _ := io.ReadAll(resp.Body) var data map[string]any json.Unmarshal(body, &data) fmt.Println(data) } ``` ```java import java.net.URI; import java.net.URLEncoder; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.nio.charset.StandardCharsets; public class Main { public static void main(String[] args) throws Exception { var apiKey = "YOUR_API_KEY"; var q = URLEncoder.encode("best python web scraping libraries", StandardCharsets.UTF_8); var url = "https://api.autom.dev/v1/google/search?q=" + q + "&gl=us&hl=en"; var client = HttpClient.newHttpClient(); var request = HttpRequest.newBuilder() .uri(URI.create(url)) .header("x-api-key", apiKey) .GET() .build(); var response = client.send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.body()); } } ``` ```csharp using System.Net.Http; var apiKey = "YOUR_API_KEY"; using var client = new HttpClient(); client.DefaultRequestHeaders.Add("x-api-key", apiKey); var url = "https://api.autom.dev/v1/google/search?q=best+python+web+scraping+libraries&gl=us&hl=en"; var response = await client.GetAsync(url); var body = await response.Content.ReadAsStringAsync(); Console.WriteLine(body); ``` ```rust use reqwest::header; #[tokio::main] async fn main() -> Result<(), reqwest::Error> { let client = reqwest::Client::new(); let response = client .get("https://api.autom.dev/v1/google/search") .header("x-api-key", "YOUR_API_KEY") .query(&[("q", "best python web scraping libraries"), ("gl", "us"), ("hl", "en")]) .send() .await? .json::() .await?; println!("{:#?}", response); Ok(()) } ``` Parse the organic results [#parse-the-organic-results] The response contains an `organic_results` array. Each entry has `position`, `title`, `link`, `snippet`, `domain`, and `source`. ```python for result in data["organic_results"]: print(f"[{result['position']}] {result['title']}") print(f" URL: {result['link']}") print(f" {result.get('snippet', '')}") print() ``` ```typescript for (const result of data.organic_results) { console.log(`[${result.position}] ${result.title}`); console.log(` URL: ${result.link}`); console.log(` ${result.snippet ?? ""}`); console.log(); } ``` ```php foreach ($data["organic_results"] as $result) { echo "[{$result['position']}] {$result['title']}\n"; echo " URL: {$result['link']}\n"; echo " " . ($result['snippet'] ?? "") . "\n\n"; } ``` ```go results := data["organic_results"].([]any) for _, r := range results { item := r.(map[string]any) fmt.Printf("[%.0f] %s\n", item["position"], item["title"]) fmt.Printf(" URL: %s\n", item["link"]) fmt.Printf(" %s\n\n", item["snippet"]) } ``` ```java import org.json.JSONArray; import org.json.JSONObject; // Add org.json:json to your build tool, or parse manually var json = new JSONObject(response.body()); var results = json.getJSONArray("organic_results"); for (int i = 0; i < results.length(); i++) { var r = results.getJSONObject(i); System.out.printf("[%d] %s%n", r.getInt("position"), r.getString("title")); System.out.printf(" URL: %s%n%n", r.getString("link")); } ``` ```csharp using System.Text.Json; var json = JsonDocument.Parse(body); var results = json.RootElement.GetProperty("organic_results").EnumerateArray(); foreach (var result in results) { Console.WriteLine($"[{result.GetProperty("position")}] {result.GetProperty("title")}"); Console.WriteLine($" URL: {result.GetProperty("link")}"); Console.WriteLine(); } ``` ```rust if let Some(results) = response["organic_results"].as_array() { for result in results { println!( "[{}] {}", result["position"], result["title"].as_str().unwrap_or("") ); println!(" URL: {}", result["link"].as_str().unwrap_or("")); println!(" {}", result["snippet"].as_str().unwrap_or("")); println!(); } } ``` Handle pagination [#handle-pagination] Use the `page` parameter to fetch subsequent pages. The response includes a `pagination` object with `has_next_page` and `next` page number. ```python import requests API_KEY = "YOUR_API_KEY" QUERY = "best python web scraping libraries" def fetch_all_results(query: str, max_pages: int = 3) -> list: all_results = [] page = 1 while page <= max_pages: response = requests.get( "https://api.autom.dev/v1/google/search", headers={"x-api-key": API_KEY}, params={"q": query, "gl": "us", "hl": "en", "page": page}, ) data = response.json() all_results.extend(data.get("organic_results", [])) if not data.get("pagination", {}).get("has_next_page"): break page += 1 return all_results results = fetch_all_results(QUERY) for r in results: print(f"[{r['position']}] {r['title']} — {r['link']}") ``` ```typescript const API_KEY = "YOUR_API_KEY"; async function fetchAllResults(query: string, maxPages = 3) { const allResults: any[] = []; let page = 1; while (page <= maxPages) { const params = new URLSearchParams({ q: query, gl: "us", hl: "en", page: String(page) }); const res = await fetch(`https://api.autom.dev/v1/google/search?${params}`, { headers: { "x-api-key": API_KEY }, }); const data = await res.json(); allResults.push(...(data.organic_results ?? [])); if (!data.pagination?.has_next_page) break; page++; } return allResults; } const results = await fetchAllResults("best python web scraping libraries"); for (const r of results) { console.log(`[${r.position}] ${r.title} — ${r.link}`); } ``` ```php $query, "gl" => "us", "hl" => "en", "page" => $page]); $ch = curl_init("https://api.autom.dev/v1/google/search?{$params}"); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_HTTPHEADER, ["x-api-key: {$apiKey}"]); $data = json_decode(curl_exec($ch), true); curl_close($ch); $allResults = array_merge($allResults, $data["organic_results"] ?? []); if (!($data["pagination"]["has_next_page"] ?? false)) break; $page++; } return $allResults; } $results = fetchAllResults("YOUR_API_KEY", "best python web scraping libraries"); foreach ($results as $r) { echo "[{$r['position']}] {$r['title']} — {$r['link']}\n"; } ``` ```go package main import ( "encoding/json" "fmt" "io" "net/http" "net/url" "strconv" ) func fetchAllResults(apiKey, query string, maxPages int) []map[string]any { var all []map[string]any for page := 1; page <= maxPages; page++ { params := url.Values{"q": {query}, "gl": {"us"}, "hl": {"en"}, "page": {strconv.Itoa(page)}} req, _ := http.NewRequest("GET", "https://api.autom.dev/v1/google/search?"+params.Encode(), nil) req.Header.Set("x-api-key", apiKey) resp, _ := http.DefaultClient.Do(req) body, _ := io.ReadAll(resp.Body) resp.Body.Close() var data map[string]any json.Unmarshal(body, &data) if items, ok := data["organic_results"].([]any); ok { for _, item := range items { all = append(all, item.(map[string]any)) } } pagination, _ := data["pagination"].(map[string]any) if pagination["has_next_page"] != true { break } } return all } func main() { results := fetchAllResults("YOUR_API_KEY", "best python web scraping libraries", 3) for _, r := range results { fmt.Printf("[%.0f] %s — %s\n", r["position"], r["title"], r["link"]) } } ``` ```java import java.net.URI; import java.net.URLEncoder; import java.net.http.*; import java.nio.charset.StandardCharsets; import java.util.*; import org.json.*; public class Main { static HttpClient client = HttpClient.newHttpClient(); static String API_KEY = "YOUR_API_KEY"; static List fetchAllResults(String query, int maxPages) throws Exception { var all = new ArrayList(); var q = URLEncoder.encode(query, StandardCharsets.UTF_8); for (int page = 1; page <= maxPages; page++) { var url = "https://api.autom.dev/v1/google/search?q=" + q + "&gl=us&hl=en&page=" + page; var request = HttpRequest.newBuilder().uri(URI.create(url)) .header("x-api-key", API_KEY).GET().build(); var resp = client.send(request, HttpResponse.BodyHandlers.ofString()); var json = new JSONObject(resp.body()); var results = json.optJSONArray("organic_results"); if (results != null) { for (int i = 0; i < results.length(); i++) all.add(results.getJSONObject(i)); } if (!json.optJSONObject("pagination").optBoolean("has_next_page")) break; } return all; } public static void main(String[] args) throws Exception { for (var r : fetchAllResults("best python web scraping libraries", 3)) { System.out.printf("[%d] %s — %s%n", r.getInt("position"), r.getString("title"), r.getString("link")); } } } ``` ```csharp using System.Net.Http; using System.Text.Json; var apiKey = "YOUR_API_KEY"; using var client = new HttpClient(); client.DefaultRequestHeaders.Add("x-api-key", apiKey); var allResults = new List(); int page = 1, maxPages = 3; while (page <= maxPages) { var url = $"https://api.autom.dev/v1/google/search?q=best+python+web+scraping+libraries&gl=us&hl=en&page={page}"; var response = await client.GetAsync(url); var body = await response.Content.ReadAsStringAsync(); var json = JsonDocument.Parse(body).RootElement; foreach (var result in json.GetProperty("organic_results").EnumerateArray()) allResults.Add(result); var hasNext = json.GetProperty("pagination").GetProperty("has_next_page").GetBoolean(); if (!hasNext) break; page++; } foreach (var r in allResults) Console.WriteLine($"[{r.GetProperty("position")}] {r.GetProperty("title")} — {r.GetProperty("link")}"); ``` ```rust use reqwest::Client; use serde_json::Value; async fn fetch_all_results(client: &Client, api_key: &str, query: &str, max_pages: u32) -> Vec { let mut all_results = Vec::new(); let mut page = 1u32; while page <= max_pages { let resp = client .get("https://api.autom.dev/v1/google/search") .header("x-api-key", api_key) .query(&[("q", query), ("gl", "us"), ("hl", "en"), ("page", &page.to_string())]) .send().await.unwrap() .json::().await.unwrap(); if let Some(results) = resp["organic_results"].as_array() { all_results.extend(results.clone()); } if !resp["pagination"]["has_next_page"].as_bool().unwrap_or(false) { break; } page += 1; } all_results } #[tokio::main] async fn main() -> Result<(), reqwest::Error> { let client = Client::new(); let results = fetch_all_results(&client, "YOUR_API_KEY", "best python web scraping libraries", 3).await; for r in &results { println!("[{}] {} — {}", r["position"], r["title"].as_str().unwrap_or(""), r["link"].as_str().unwrap_or("")); } Ok(()) } ``` Use the `gl` parameter to target a specific country (e.g. `fr` for France, `de` for Germany) and `hl` for the language of results. This is essential for accurate local rank tracking. # Analyze a Page with AI Overview [#overview] The CaptureKit AI analysis endpoint combines screenshot capture with LLM-powered analysis. Pass any URL and a custom `prompt` — the API returns a structured JSON answer grounded in what the page actually looks like. Use it for **competitor audits**, **UX reviews**, or **automated content QA**. Prerequisites [#prerequisites] * A CaptureKit API key — get one at [app.capturekit.dev](https://app.capturekit.dev) * Install dependencies for your language: ```bash pip install requests ``` No extra dependencies — uses the native `fetch` API (Node 18+). `curl` extension enabled (on by default). No extra dependencies — uses `net/http` (Go 1.18+). No extra dependencies — uses `java.net.http` (Java 11+). No extra dependencies — uses `System.Net.Http` (.NET 6+). ```toml # Cargo.toml [dependencies] reqwest = { version = "0.12", features = ["json"] } tokio = { version = "1", features = ["full"] } serde_json = "1" ``` Steps [#steps] Submit an analysis request [#submit-an-analysis-request] Call `GET /v1/analyze` with the `url` and `prompt` parameters. The `prompt` shapes the AI's response. ```python import requests API_KEY = "YOUR_API_KEY" PROMPT = "Summarize the main value proposition of this page in 2 sentences. Then list the top 3 CTAs visible above the fold." response = requests.get( "https://api.capturekit.dev/v1/analyze", headers={"x-api-key": API_KEY}, params={"url": "https://stripe.com", "prompt": PROMPT}, ) data = response.json() print(data) ``` ```typescript const API_KEY = "YOUR_API_KEY"; const PROMPT = "Summarize the main value proposition of this page in 2 sentences. Then list the top 3 CTAs visible above the fold."; const params = new URLSearchParams({ url: "https://stripe.com", prompt: PROMPT }); const response = await fetch(`https://api.capturekit.dev/v1/analyze?${params}`, { headers: { "x-api-key": API_KEY }, }); const data = await response.json(); console.log(data); ``` ```php "https://stripe.com", "prompt" => $prompt]); $ch = curl_init("https://api.capturekit.dev/v1/analyze?{$params}"); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_HTTPHEADER, ["x-api-key: {$apiKey}"]); $data = json_decode(curl_exec($ch), true); curl_close($ch); print_r($data); ``` ```go package main import ( "encoding/json" "fmt" "io" "net/http" "net/url" ) func main() { params := url.Values{ "url": {"https://stripe.com"}, "prompt": {"Summarize the main value proposition in 2 sentences. List the top 3 CTAs above the fold."}, } req, _ := http.NewRequest("GET", "https://api.capturekit.dev/v1/analyze?"+params.Encode(), nil) req.Header.Set("x-api-key", "YOUR_API_KEY") resp, _ := http.DefaultClient.Do(req) defer resp.Body.Close() body, _ := io.ReadAll(resp.Body) var data map[string]any json.Unmarshal(body, &data) fmt.Println(data) } ``` ```java import java.net.URI; import java.net.URLEncoder; import java.net.http.*; import java.nio.charset.StandardCharsets; var client = HttpClient.newHttpClient(); var prompt = URLEncoder.encode("Summarize the value proposition in 2 sentences. List the top 3 CTAs above the fold.", StandardCharsets.UTF_8); var request = HttpRequest.newBuilder() .uri(URI.create("https://api.capturekit.dev/v1/analyze?url=https%3A%2F%2Fstripe.com&prompt=" + prompt)) .header("x-api-key", "YOUR_API_KEY").GET().build(); var response = client.send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.body()); ``` ```csharp using System.Net.Http; using var client = new HttpClient(); client.DefaultRequestHeaders.Add("x-api-key", "YOUR_API_KEY"); var prompt = Uri.EscapeDataString("Summarize the value proposition in 2 sentences. List the top 3 CTAs above the fold."); var body = await client.GetStringAsync( $"https://api.capturekit.dev/v1/analyze?url=https%3A%2F%2Fstripe.com&prompt={prompt}"); Console.WriteLine(body); ``` ```rust #[tokio::main] async fn main() -> Result<(), reqwest::Error> { let data = reqwest::Client::new() .get("https://api.capturekit.dev/v1/analyze") .header("x-api-key", "YOUR_API_KEY") .query(&[ ("url", "https://stripe.com"), ("prompt", "Summarize the value proposition in 2 sentences. List the top 3 CTAs above the fold."), ]) .send().await?.json::().await?; println!("{:#?}", data); Ok(()) } ``` Read the AI analysis [#read-the-ai-analysis] The response includes `analysis` (the AI's answer to your prompt), `screenshot_url`, and metadata like `title` and `description`. ```python print(f"Page : {data.get('title')}") print(f"Preview : {data.get('screenshot_url')}") print() print("=== AI Analysis ===") print(data.get("analysis", "")) ``` ```typescript console.log(`Page : ${data.title}`); console.log(`Preview : ${data.screenshot_url}\n`); console.log("=== AI Analysis ==="); console.log(data.analysis); ``` ```php echo "Page : {$data['title']}\n"; echo "Preview : {$data['screenshot_url']}\n\n"; echo "=== AI Analysis ===\n"; echo $data["analysis"] ?? ""; ``` ```go fmt.Printf("Page : %v\nPreview : %v\n\n=== AI Analysis ===\n%v\n", data["title"], data["screenshot_url"], data["analysis"]) ``` ```java import org.json.*; var d = new JSONObject(response.body()); System.out.printf("Page : %s%nPreview : %s%n%n=== AI Analysis ===%n%s%n", d.getString("title"), d.getString("screenshot_url"), d.getString("analysis")); ``` ```csharp using System.Text.Json; var d = JsonDocument.Parse(body).RootElement; Console.WriteLine($"Page : {d.GetProperty("title")}"); Console.WriteLine($"Preview : {d.GetProperty("screenshot_url")}\n"); Console.WriteLine("=== AI Analysis ==="); Console.WriteLine(d.GetProperty("analysis")); ``` ```rust println!("Page : {}", data["title"].as_str().unwrap_or("")); println!("Preview : {}\n", data["screenshot_url"].as_str().unwrap_or("")); println!("=== AI Analysis ==="); println!("{}", data["analysis"].as_str().unwrap_or("")); ``` Run a competitor audit across multiple pages [#run-a-competitor-audit-across-multiple-pages] Analyze several competitor landing pages with a consistent prompt and save the results as a structured report. ````python import json, time, requests API_KEY = "YOUR_API_KEY" PROMPT = """Analyze this landing page and return a JSON object with these keys: - value_proposition (string) - primary_cta (string) - target_audience (string) - pricing_visible (boolean) - social_proof_types (array of strings: "testimonials", "logos", "stats", etc.)""" COMPETITORS = [ {"name": "Stripe", "url": "https://stripe.com"}, {"name": "Paddle", "url": "https://paddle.com"}, {"name": "Lemonsqueezy", "url": "https://lemonsqueezy.com"}, ] report = [] for comp in COMPETITORS: r = requests.get("https://api.capturekit.dev/v1/analyze", headers={"x-api-key": API_KEY}, params={"url": comp["url"], "prompt": PROMPT}) data = r.json() analysis_text = data.get("analysis", "{}") try: # AI may return the JSON wrapped in markdown fences raw = analysis_text.strip().removeprefix("```json").removesuffix("```").strip() analysis = json.loads(raw) except json.JSONDecodeError: analysis = {"raw": analysis_text} report.append({"competitor": comp["name"], "url": comp["url"], **analysis}) print(f"✓ {comp['name']} analyzed") time.sleep(2) with open("competitor_audit.json", "w") as f: json.dump(report, f, indent=2) print("\nReport saved to competitor_audit.json") ```` ````typescript import { writeFileSync } from "fs"; const API_KEY = "YOUR_API_KEY"; const PROMPT = `Analyze this landing page and return a JSON object with these keys: - value_proposition (string) - primary_cta (string) - target_audience (string) - pricing_visible (boolean) - social_proof_types (array of strings)`; const competitors = [ { name: "Stripe", url: "https://stripe.com" }, { name: "Paddle", url: "https://paddle.com" }, { name: "Lemonsqueezy", url: "https://lemonsqueezy.com" }, ]; const report: any[] = []; for (const comp of competitors) { const params = new URLSearchParams({ url: comp.url, prompt: PROMPT }); const res = await fetch(`https://api.capturekit.dev/v1/analyze?${params}`, { headers: { "x-api-key": API_KEY }, }); const data = await res.json(); let analysis: any; try { const raw = (data.analysis ?? "{}").replace(/^```json\n?/, "").replace(/```$/, "").trim(); analysis = JSON.parse(raw); } catch { analysis = { raw: data.analysis }; } report.push({ competitor: comp.name, url: comp.url, ...analysis }); console.log(`✓ ${comp.name} analyzed`); await new Promise(r => setTimeout(r, 2000)); } writeFileSync("competitor_audit.json", JSON.stringify(report, null, 2)); console.log("\nReport saved to competitor_audit.json"); ```` ````php "Stripe", "url" => "https://stripe.com"], ["name" => "Paddle", "url" => "https://paddle.com"], ["name" => "Lemonsqueezy", "url" => "https://lemonsqueezy.com"], ]; $report = []; foreach ($competitors as $comp) { $params = http_build_query(["url" => $comp["url"], "prompt" => $prompt]); $ch = curl_init("https://api.capturekit.dev/v1/analyze?{$params}"); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_HTTPHEADER, ["x-api-key: {$apiKey}"]); $data = json_decode(curl_exec($ch), true); curl_close($ch); $raw = preg_replace('/^```json\n?|```$/', '', trim($data["analysis"] ?? "{}")); $analysis = json_decode($raw, true) ?? ["raw" => $data["analysis"]]; $report[] = array_merge(["competitor" => $comp["name"], "url" => $comp["url"]], $analysis); echo "✓ {$comp['name']} analyzed\n"; sleep(2); } file_put_contents("competitor_audit.json", json_encode($report, JSON_PRETTY_PRINT)); echo "\nReport saved to competitor_audit.json\n"; ```` ````go package main import ( "encoding/json" "fmt" "io" "net/http" "net/url" "os" "strings" "time" ) const ( APIKey = "YOUR_API_KEY" Prompt = "Analyze this landing page and return a JSON object: value_proposition, primary_cta, target_audience, pricing_visible, social_proof_types." ) type Competitor struct{ Name, URL string } func analyze(comp Competitor) map[string]any { params := url.Values{"url": {comp.URL}, "prompt": {Prompt}} req, _ := http.NewRequest("GET", "https://api.capturekit.dev/v1/analyze?"+params.Encode(), nil) req.Header.Set("x-api-key", APIKey) resp, _ := http.DefaultClient.Do(req) body, _ := io.ReadAll(resp.Body) resp.Body.Close() var data map[string]any json.Unmarshal(body, &data) raw := strings.TrimSpace(fmt.Sprint(data["analysis"])) raw = strings.TrimPrefix(raw, "```json") raw = strings.TrimSuffix(raw, "```") var analysis map[string]any if err := json.Unmarshal([]byte(strings.TrimSpace(raw)), &analysis); err != nil { analysis = map[string]any{"raw": raw} } analysis["competitor"] = comp.Name analysis["url"] = comp.URL return analysis } func main() { competitors := []Competitor{ {"Stripe", "https://stripe.com"}, {"Paddle", "https://paddle.com"}, {"Lemonsqueezy", "https://lemonsqueezy.com"}, } var report []map[string]any for _, c := range competitors { report = append(report, analyze(c)) fmt.Printf("✓ %s analyzed\n", c.Name) time.Sleep(2 * time.Second) } b, _ := json.MarshalIndent(report, "", " ") os.WriteFile("competitor_audit.json", b, 0644) fmt.Println("\nReport saved to competitor_audit.json") } ```` ````java import java.net.URI; import java.net.URLEncoder; import java.net.http.*; import java.nio.charset.StandardCharsets; import java.nio.file.*; import java.util.*; import org.json.*; public class Main { static final String API_KEY = "YOUR_API_KEY"; static final String PROMPT = "Analyze this landing page and return a JSON object: value_proposition, primary_cta, target_audience, pricing_visible, social_proof_types."; public static void main(String[] args) throws Exception { var client = HttpClient.newHttpClient(); var competitors = List.of( Map.of("name","Stripe", "url","https://stripe.com"), Map.of("name","Paddle", "url","https://paddle.com"), Map.of("name","Lemonsqueezy", "url","https://lemonsqueezy.com")); var report = new JSONArray(); for (var comp : competitors) { var encodedUrl = URLEncoder.encode(comp.get("url"), StandardCharsets.UTF_8); var encodedPrompt = URLEncoder.encode(PROMPT, StandardCharsets.UTF_8); var req = HttpRequest.newBuilder() .uri(URI.create("https://api.capturekit.dev/v1/analyze?url=" + encodedUrl + "&prompt=" + encodedPrompt)) .header("x-api-key", API_KEY).GET().build(); var resp = client.send(req, HttpResponse.BodyHandlers.ofString()); var data = new JSONObject(resp.body()); var analysisText = data.getString("analysis") .replaceAll("^```json\\n?","").replaceAll("```$","").strip(); JSONObject analysis; try { analysis = new JSONObject(analysisText); } catch (Exception e) { analysis = new JSONObject().put("raw", analysisText); } analysis.put("competitor", comp.get("name")).put("url", comp.get("url")); report.put(analysis); System.out.println("✓ " + comp.get("name") + " analyzed"); Thread.sleep(2000); } Files.writeString(Path.of("competitor_audit.json"), report.toString(2)); System.out.println("\nReport saved to competitor_audit.json"); } } ```` ````csharp using System.Net.Http; using System.Text.Json; using System.Text.RegularExpressions; const string API_KEY = "YOUR_API_KEY"; const string PROMPT = "Analyze this landing page and return a JSON object: value_proposition, primary_cta, target_audience, pricing_visible, social_proof_types."; using var client = new HttpClient(); client.DefaultRequestHeaders.Add("x-api-key", API_KEY); var competitors = new[] { (name: "Stripe", url: "https://stripe.com"), (name: "Paddle", url: "https://paddle.com"), (name: "Lemonsqueezy", url: "https://lemonsqueezy.com"), }; var report = new List(); foreach (var comp in competitors) { var encodedUrl = Uri.EscapeDataString(comp.url); var encodedPrompt = Uri.EscapeDataString(PROMPT); var body = await client.GetStringAsync($"https://api.capturekit.dev/v1/analyze?url={encodedUrl}&prompt={encodedPrompt}"); var data = JsonDocument.Parse(body).RootElement; var analysisText = data.GetProperty("analysis").GetString() ?? "{}"; var clean = Regex.Replace(analysisText.Trim(), @"^```json\n?|```$", "").Trim(); object analysis; try { analysis = JsonSerializer.Deserialize>(clean)!; } catch { analysis = new { raw = analysisText }; } report.Add(new { competitor = comp.name, comp.url, analysis }); Console.WriteLine($"✓ {comp.name} analyzed"); await Task.Delay(2000); } File.WriteAllText("competitor_audit.json", JsonSerializer.Serialize(report, new JsonSerializerOptions { WriteIndented = true })); Console.WriteLine("\nReport saved to competitor_audit.json"); ```` ````rust use reqwest::Client; use serde_json::{json, Value}; use std::{fs, time::Duration}; use tokio::time::sleep; const API_KEY: &str = "YOUR_API_KEY"; const PROMPT: &str = "Analyze this landing page and return a JSON object: value_proposition, primary_cta, target_audience, pricing_visible, social_proof_types."; #[tokio::main] async fn main() -> Result<(), reqwest::Error> { let client = Client::new(); let competitors = [("Stripe","https://stripe.com"), ("Paddle","https://paddle.com"), ("Lemonsqueezy","https://lemonsqueezy.com")]; let mut report = Vec::new(); for (name, url) in &competitors { let data = client.get("https://api.capturekit.dev/v1/analyze") .header("x-api-key", API_KEY) .query(&[("url", url), ("prompt", &PROMPT)]) .send().await?.json::().await?; let analysis_text = data["analysis"].as_str().unwrap_or("{}"); let clean = analysis_text.trim().trim_start_matches("```json").trim_end_matches("```").trim(); let analysis: Value = serde_json::from_str(clean).unwrap_or(json!({ "raw": analysis_text })); report.push(json!({ "competitor": name, "url": url, "analysis": analysis })); println!("✓ {} analyzed", name); sleep(Duration::from_secs(2)).await; } fs::write("competitor_audit.json", serde_json::to_string_pretty(&report).unwrap()).unwrap(); println!("\nReport saved to competitor_audit.json"); Ok(()) } ```` Instruct the AI to return structured JSON in your `prompt` — the model will format its output accordingly, making it easy to parse and store results in a database or spreadsheet without additional post-processing. # Extract Content as Markdown Overview [#overview] The CaptureKit content endpoint fetches a webpage, strips navigation, ads, and layout chrome, then returns the main body as **clean Markdown**. Use it for building RAG datasets, indexing documentation, or archiving articles. Prerequisites [#prerequisites] * A CaptureKit API key — get one at [app.capturekit.dev](https://app.capturekit.dev) * Install dependencies for your language: ```bash pip install requests ``` No extra dependencies — uses the native `fetch` API (Node 18+). `curl` extension enabled (on by default). No extra dependencies — uses `net/http` (Go 1.18+). No extra dependencies — uses `java.net.http` (Java 11+). No extra dependencies — uses `System.Net.Http` (.NET 6+). ```toml # Cargo.toml [dependencies] reqwest = { version = "0.12", features = ["json"] } tokio = { version = "1", features = ["full"] } serde_json = "1" ``` Steps [#steps] Fetch the page content [#fetch-the-page-content] Call `GET /v1/content` with the `url` parameter. ```python import requests API_KEY = "YOUR_API_KEY" response = requests.get( "https://api.capturekit.dev/v1/content", headers={"x-api-key": API_KEY}, params={"url": "https://stripe.com/docs/payments"}, ) data = response.json() print(data) ``` ```typescript const API_KEY = "YOUR_API_KEY"; const params = new URLSearchParams({ url: "https://stripe.com/docs/payments" }); const response = await fetch(`https://api.capturekit.dev/v1/content?${params}`, { headers: { "x-api-key": API_KEY }, }); const data = await response.json(); console.log(data); ``` ```php "https://stripe.com/docs/payments"]); $ch = curl_init("https://api.capturekit.dev/v1/content?{$params}"); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_HTTPHEADER, ["x-api-key: {$apiKey}"]); $data = json_decode(curl_exec($ch), true); curl_close($ch); print_r($data); ``` ```go package main import ( "encoding/json" "fmt" "io" "net/http" "net/url" ) func main() { params := url.Values{"url": {"https://stripe.com/docs/payments"}} req, _ := http.NewRequest("GET", "https://api.capturekit.dev/v1/content?"+params.Encode(), nil) req.Header.Set("x-api-key", "YOUR_API_KEY") resp, _ := http.DefaultClient.Do(req) defer resp.Body.Close() body, _ := io.ReadAll(resp.Body) var data map[string]any json.Unmarshal(body, &data) fmt.Println(data) } ``` ```java import java.net.URI; import java.net.URLEncoder; import java.net.http.*; import java.nio.charset.StandardCharsets; var client = HttpClient.newHttpClient(); var target = URLEncoder.encode("https://stripe.com/docs/payments", StandardCharsets.UTF_8); var request = HttpRequest.newBuilder() .uri(URI.create("https://api.capturekit.dev/v1/content?url=" + target)) .header("x-api-key", "YOUR_API_KEY").GET().build(); var response = client.send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.body()); ``` ```csharp using System.Net.Http; using var client = new HttpClient(); client.DefaultRequestHeaders.Add("x-api-key", "YOUR_API_KEY"); var target = Uri.EscapeDataString("https://stripe.com/docs/payments"); var body = await client.GetStringAsync($"https://api.capturekit.dev/v1/content?url={target}"); Console.WriteLine(body); ``` ```rust #[tokio::main] async fn main() -> Result<(), reqwest::Error> { let data = reqwest::Client::new() .get("https://api.capturekit.dev/v1/content") .header("x-api-key", "YOUR_API_KEY") .query(&[("url", "https://stripe.com/docs/payments")]) .send().await?.json::().await?; println!("{:#?}", data); Ok(()) } ``` Access the Markdown content [#access-the-markdown-content] The response includes `markdown`, `title`, `description`, `author`, `published_at`, and `word_count`. ```python print(f"Title : {data.get('title')}") print(f"Author : {data.get('author', 'N/A')}") print(f"Word count : {data.get('word_count')} words") print() print("--- Markdown preview ---") markdown = data.get("markdown", "") print(markdown[:1000]) ``` ```typescript console.log(`Title : ${data.title}`); console.log(`Author : ${data.author ?? "N/A"}`); console.log(`Word count : ${data.word_count} words\n`); console.log("--- Markdown preview ---"); console.log(data.markdown?.slice(0, 1000)); ``` ```php echo "Title : {$data['title']}\n"; echo "Author : " . ($data["author"] ?? "N/A") . "\n"; echo "Word count : {$data['word_count']} words\n\n"; echo "--- Markdown preview ---\n"; echo substr($data["markdown"] ?? "", 0, 1000) . "\n"; ``` ```go fmt.Printf("Title : %v\nAuthor : %v\nWord count : %v words\n\n", data["title"], data["author"], data["word_count"]) markdown := data["markdown"].(string) if len(markdown) > 1000 { markdown = markdown[:1000] } fmt.Println("--- Markdown preview ---\n" + markdown) ``` ```java import org.json.*; var d = new JSONObject(response.body()); var markdown = d.getString("markdown"); System.out.printf("Title : %s%nAuthor : %s%nWord count : %d words%n%n", d.getString("title"), d.optString("author", "N/A"), d.getInt("word_count")); System.out.println("--- Markdown preview ---"); System.out.println(markdown.substring(0, Math.min(1000, markdown.length()))); ``` ```csharp using System.Text.Json; var d = JsonDocument.Parse(body).RootElement; var markdown = d.GetProperty("markdown").GetString() ?? ""; Console.WriteLine($"Title : {d.GetProperty("title")}"); Console.WriteLine($"Author : {(d.TryGetProperty("author", out var a) ? a : (object)"N/A")}"); Console.WriteLine($"Word count : {d.GetProperty("word_count")} words\n"); Console.WriteLine("--- Markdown preview ---"); Console.WriteLine(markdown[..Math.Min(1000, markdown.Length)]); ``` ```rust let markdown = data["markdown"].as_str().unwrap_or(""); println!("Title : {}", data["title"].as_str().unwrap_or("")); println!("Author : {}", data["author"].as_str().unwrap_or("N/A")); println!("Word count : {} words\n", data["word_count"]); println!("--- Markdown preview ---"); println!("{}", &markdown[..1000.min(markdown.len())]); ``` Crawl and archive a list of documentation pages [#crawl-and-archive-a-list-of-documentation-pages] Fetch and save multiple pages as Markdown files for offline search or RAG ingestion. ```python import os, time, requests API_KEY = "YOUR_API_KEY" os.makedirs("docs_archive", exist_ok=True) PAGES = [ "https://stripe.com/docs/payments", "https://stripe.com/docs/billing", "https://stripe.com/docs/connect", ] for page_url in PAGES: r = requests.get("https://api.capturekit.dev/v1/content", headers={"x-api-key": API_KEY}, params={"url": page_url}) data = r.json() slug = page_url.rstrip("/").split("/")[-1] path = f"docs_archive/{slug}.md" with open(path, "w") as f: f.write(f"# {data.get('title', slug)}\n\n") f.write(data.get("markdown", "")) print(f"Saved: {path} ({data.get('word_count', 0)} words)") time.sleep(1) print("Done!") ``` ```typescript import { mkdirSync, writeFileSync } from "fs"; const API_KEY = "YOUR_API_KEY"; mkdirSync("docs_archive", { recursive: true }); const PAGES = [ "https://stripe.com/docs/payments", "https://stripe.com/docs/billing", "https://stripe.com/docs/connect", ]; for (const pageUrl of PAGES) { const params = new URLSearchParams({ url: pageUrl }); const res = await fetch(`https://api.capturekit.dev/v1/content?${params}`, { headers: { "x-api-key": API_KEY }, }); const data = await res.json(); const slug = pageUrl.replace(/\/$/, "").split("/").at(-1)!; writeFileSync(`docs_archive/${slug}.md`, `# ${data.title ?? slug}\n\n${data.markdown ?? ""}`); console.log(`Saved: docs_archive/${slug}.md (${data.word_count ?? 0} words)`); await new Promise(r => setTimeout(r, 1000)); } console.log("Done!"); ``` ```php $pageUrl]); $ch = curl_init("https://api.capturekit.dev/v1/content?{$params}"); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_HTTPHEADER, ["x-api-key: {$apiKey}"]); $data = json_decode(curl_exec($ch), true); curl_close($ch); $slug = basename(rtrim($pageUrl, "/")); $path = "docs_archive/{$slug}.md"; file_put_contents($path, "# {$data['title']}\n\n{$data['markdown']}"); echo "Saved: {$path} ({$data['word_count']} words)\n"; sleep(1); } echo "Done!\n"; ``` ```go package main import ( "encoding/json" "fmt" "io" "net/http" "net/url" "os" "path/filepath" "strings" "time" ) func main() { os.MkdirAll("docs_archive", 0755) apiKey := "YOUR_API_KEY" pages := []string{ "https://stripe.com/docs/payments", "https://stripe.com/docs/billing", "https://stripe.com/docs/connect", } for _, pageURL := range pages { params := url.Values{"url": {pageURL}} req, _ := http.NewRequest("GET", "https://api.capturekit.dev/v1/content?"+params.Encode(), nil) req.Header.Set("x-api-key", apiKey) resp, _ := http.DefaultClient.Do(req) body, _ := io.ReadAll(resp.Body) resp.Body.Close() var data map[string]any json.Unmarshal(body, &data) parts := strings.Split(strings.TrimRight(pageURL, "/"), "/") slug := parts[len(parts)-1] path := filepath.Join("docs_archive", slug+".md") content := fmt.Sprintf("# %v\n\n%v", data["title"], data["markdown"]) os.WriteFile(path, []byte(content), 0644) fmt.Printf("Saved: %s (%.0f words)\n", path, data["word_count"]) time.Sleep(time.Second) } fmt.Println("Done!") } ``` ```java import java.net.URI; import java.net.URLEncoder; import java.net.http.*; import java.nio.charset.StandardCharsets; import java.nio.file.*; import java.util.List; import org.json.*; public class Main { public static void main(String[] args) throws Exception { var client = HttpClient.newHttpClient(); var apiKey = "YOUR_API_KEY"; Files.createDirectories(Path.of("docs_archive")); var pages = List.of( "https://stripe.com/docs/payments", "https://stripe.com/docs/billing", "https://stripe.com/docs/connect"); for (var pageUrl : pages) { var encoded = URLEncoder.encode(pageUrl, StandardCharsets.UTF_8); var req = HttpRequest.newBuilder() .uri(URI.create("https://api.capturekit.dev/v1/content?url=" + encoded)) .header("x-api-key", apiKey).GET().build(); var resp = client.send(req, HttpResponse.BodyHandlers.ofString()); var data = new JSONObject(resp.body()); var slug = pageUrl.replaceAll("/$","").replaceAll(".*/",""); var content = "# " + data.getString("title") + "\n\n" + data.getString("markdown"); Files.writeString(Path.of("docs_archive/" + slug + ".md"), content); System.out.printf("Saved: docs_archive/%s.md (%d words)%n", slug, data.getInt("word_count")); Thread.sleep(1000); } System.out.println("Done!"); } } ``` ```csharp using System.Net.Http; using System.Text.Json; var apiKey = "YOUR_API_KEY"; using var client = new HttpClient(); client.DefaultRequestHeaders.Add("x-api-key", apiKey); Directory.CreateDirectory("docs_archive"); var pages = new[] { "https://stripe.com/docs/payments", "https://stripe.com/docs/billing", "https://stripe.com/docs/connect", }; foreach (var pageUrl in pages) { var encoded = Uri.EscapeDataString(pageUrl); var body = await client.GetStringAsync($"https://api.capturekit.dev/v1/content?url={encoded}"); var data = JsonDocument.Parse(body).RootElement; var slug = pageUrl.TrimEnd('/').Split('/').Last(); var content = $"# {data.GetProperty("title")}\n\n{data.GetProperty("markdown")}"; File.WriteAllText($"docs_archive/{slug}.md", content); Console.WriteLine($"Saved: docs_archive/{slug}.md ({data.GetProperty("word_count")} words)"); await Task.Delay(1000); } Console.WriteLine("Done!"); ``` ```rust use reqwest::Client; use serde_json::Value; use std::{fs, path::Path, time::Duration}; use tokio::time::sleep; #[tokio::main] async fn main() -> Result<(), reqwest::Error> { let client = Client::new(); let api_key = "YOUR_API_KEY"; let pages = ["https://stripe.com/docs/payments", "https://stripe.com/docs/billing", "https://stripe.com/docs/connect"]; fs::create_dir_all("docs_archive").unwrap(); for page_url in &pages { let data = client.get("https://api.capturekit.dev/v1/content") .header("x-api-key", api_key) .query(&[("url", page_url)]) .send().await?.json::().await?; let slug = page_url.trim_end_matches('/').split('/').last().unwrap_or("page"); let path = format!("docs_archive/{}.md", slug); let content = format!("# {}\n\n{}", data["title"].as_str().unwrap_or(""), data["markdown"].as_str().unwrap_or("")); fs::write(&path, content).unwrap(); println!("Saved: {} ({} words)", path, data["word_count"]); sleep(Duration::from_secs(1)).await; } println!("Done!"); Ok(()) } ``` The extracted Markdown is ideal as context chunks for a RAG (Retrieval-Augmented Generation) pipeline. Chunk by headings and embed with your preferred vector store for semantic search over any website's documentation. # Screenshot a Webpage Overview [#overview] This playbook shows how to take a screenshot of any public URL and save it to disk. A common use case is **visual regression testing** or generating OG image thumbnails for a link-preview service. Prerequisites [#prerequisites] * A CaptureKit API key — get one at [app.capturekit.dev](https://app.capturekit.dev) * Install dependencies for your language: ```bash pip install requests ``` No extra dependencies — uses the native `fetch` API (Node 18+). `curl` extension enabled (on by default). No extra dependencies — uses `net/http` (Go 1.18+). No extra dependencies — uses `java.net.http` (Java 11+). No extra dependencies — uses `System.Net.Http` (.NET 6+). ```toml # Cargo.toml [dependencies] reqwest = { version = "0.12", features = ["json"] } tokio = { version = "1", features = ["full"] } serde_json = "1" ``` Steps [#steps] Request a screenshot [#request-a-screenshot] Call `GET /v1/capture` with the `url` parameter. Additional options control the viewport, format, and full-page capture. ```python import requests API_KEY = "YOUR_API_KEY" response = requests.get( "https://api.capturekit.dev/v1/capture", headers={"x-api-key": API_KEY}, params={ "url": "https://stripe.com", "format": "png", "full_page": "true", "width": "1440", "height": "900", }, ) data = response.json() print(data) ``` ```typescript const API_KEY = "YOUR_API_KEY"; const params = new URLSearchParams({ url: "https://stripe.com", format: "png", full_page: "true", width: "1440", height: "900", }); const response = await fetch(`https://api.capturekit.dev/v1/capture?${params}`, { headers: { "x-api-key": API_KEY }, }); const data = await response.json(); console.log(data); ``` ```php "https://stripe.com", "format" => "png", "full_page" => "true", "width" => "1440", "height" => "900", ]); $ch = curl_init("https://api.capturekit.dev/v1/capture?{$params}"); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_HTTPHEADER, ["x-api-key: {$apiKey}"]); $data = json_decode(curl_exec($ch), true); curl_close($ch); print_r($data); ``` ```go package main import ( "encoding/json" "fmt" "io" "net/http" "net/url" ) func main() { params := url.Values{ "url": {"https://stripe.com"}, "format": {"png"}, "full_page": {"true"}, "width": {"1440"}, "height": {"900"}, } req, _ := http.NewRequest("GET", "https://api.capturekit.dev/v1/capture?"+params.Encode(), nil) req.Header.Set("x-api-key", "YOUR_API_KEY") resp, _ := http.DefaultClient.Do(req) defer resp.Body.Close() body, _ := io.ReadAll(resp.Body) var data map[string]any json.Unmarshal(body, &data) fmt.Println(data) } ``` ```java import java.net.URI; import java.net.URLEncoder; import java.net.http.*; import java.nio.charset.StandardCharsets; var apiKey = "YOUR_API_KEY"; var target = URLEncoder.encode("https://stripe.com", StandardCharsets.UTF_8); var url = "https://api.capturekit.dev/v1/capture?url=" + target + "&format=png&full_page=true&width=1440&height=900"; var client = HttpClient.newHttpClient(); var request = HttpRequest.newBuilder().uri(URI.create(url)) .header("x-api-key", apiKey).GET().build(); var response = client.send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.body()); ``` ```csharp using System.Net.Http; using var client = new HttpClient(); client.DefaultRequestHeaders.Add("x-api-key", "YOUR_API_KEY"); var target = Uri.EscapeDataString("https://stripe.com"); var body = await client.GetStringAsync( $"https://api.capturekit.dev/v1/capture?url={target}&format=png&full_page=true&width=1440&height=900"); Console.WriteLine(body); ``` ```rust #[tokio::main] async fn main() -> Result<(), reqwest::Error> { let data = reqwest::Client::new() .get("https://api.capturekit.dev/v1/capture") .header("x-api-key", "YOUR_API_KEY") .query(&[("url", "https://stripe.com"), ("format", "png"), ("full_page", "true"), ("width", "1440"), ("height", "900")]) .send().await?.json::().await?; println!("{:#?}", data); Ok(()) } ``` Get the image URL from the response [#get-the-image-url-from-the-response] The API returns a `screenshot_url` with the hosted image — or a base64-encoded `image` field if you set `response_type=base64`. ```python screenshot_url = data.get("screenshot_url") print(f"Screenshot ready: {screenshot_url}") ``` ```typescript const { screenshot_url } = data; console.log(`Screenshot ready: ${screenshot_url}`); ``` ```php $screenshotUrl = $data["screenshot_url"] ?? ""; echo "Screenshot ready: {$screenshotUrl}\n"; ``` ```go screenshotURL := data["screenshot_url"].(string) fmt.Println("Screenshot ready:", screenshotURL) ``` ```java import org.json.*; var screenshotUrl = new JSONObject(response.body()).getString("screenshot_url"); System.out.println("Screenshot ready: " + screenshotUrl); ``` ```csharp using System.Text.Json; var screenshotUrl = JsonDocument.Parse(body).RootElement.GetProperty("screenshot_url").GetString(); Console.WriteLine($"Screenshot ready: {screenshotUrl}"); ``` ```rust let screenshot_url = data["screenshot_url"].as_str().unwrap_or(""); println!("Screenshot ready: {}", screenshot_url); ``` Download and save the image [#download-and-save-the-image] Fetch the image bytes from the URL and write them to disk. ```python filename = "screenshot.png" with requests.get(screenshot_url, stream=True) as r: r.raise_for_status() with open(filename, "wb") as f: for chunk in r.iter_content(chunk_size=8192): f.write(chunk) print(f"Saved to {filename}") ``` ```typescript import { writeFileSync } from "fs"; const imgResponse = await fetch(screenshotUrl); const buffer = Buffer.from(await imgResponse.arrayBuffer()); writeFileSync("screenshot.png", buffer); console.log("Saved to screenshot.png"); ``` ```php $fp = fopen("screenshot.png", "wb"); $ch = curl_init($screenshotUrl); curl_setopt($ch, CURLOPT_FILE, $fp); curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true); curl_exec($ch); curl_close($ch); fclose($fp); echo "Saved to screenshot.png\n"; ``` ```go import "os" resp, _ := http.Get(screenshotURL) defer resp.Body.Close() file, _ := os.Create("screenshot.png") defer file.Close() io.Copy(file, resp.Body) fmt.Println("Saved to screenshot.png") ``` ```java import java.net.URL; import java.nio.file.*; Files.copy(new URL(screenshotUrl).openStream(), Path.of("screenshot.png"), StandardCopyOption.REPLACE_EXISTING); System.out.println("Saved to screenshot.png"); ``` ```csharp var imageBytes = await new HttpClient().GetByteArrayAsync(screenshotUrl); File.WriteAllBytes("screenshot.png", imageBytes); Console.WriteLine("Saved to screenshot.png"); ``` ```rust use std::{fs::File, io::Write}; let bytes = reqwest::get(screenshot_url).await?.bytes().await?; let mut file = File::create("screenshot.png").unwrap(); file.write_all(&bytes).unwrap(); println!("Saved to screenshot.png"); ``` Use `full_page=false` to capture only the above-the-fold viewport — ideal for social media preview thumbnails where a fixed-height 630×1200 px crop is required. # Extract Audio from a Video Overview [#overview] By passing `quality: "audio"` to the HuntAPI downloader, you get an MP3 extract instead of the full video. This playbook builds a complete audio extraction pipeline including job submission, polling, and saving. Prerequisites [#prerequisites] * A HuntAPI key — get one at [app.huntapi.com](https://app.huntapi.com) * Install dependencies for your language: ```bash pip install requests ``` No extra dependencies — uses the native `fetch` API (Node 18+). `curl` extension enabled (on by default). No extra dependencies — uses `net/http` (Go 1.18+). No extra dependencies — uses `java.net.http` (Java 11+). No extra dependencies — uses `System.Net.Http` (.NET 6+). ```toml # Cargo.toml [dependencies] reqwest = { version = "0.12", features = ["json"] } tokio = { version = "1", features = ["full"] } serde_json = "1" ``` Steps [#steps] Submit an audio extraction job [#submit-an-audio-extraction-job] Use the same `/v1/video/download` endpoint with `quality=audio`. ```python import requests API_KEY = "YOUR_API_KEY" VIDEO_URL = "https://www.youtube.com/watch?v=dQw4w9WgXcQ" response = requests.get( "https://api.huntapi.com/v1/video/download", headers={"x-api-key": API_KEY}, params={"url": VIDEO_URL, "quality": "audio"}, ) data = response.json() job_id = data["job_id"] print(f"Audio job submitted: {job_id}") ``` ```typescript const API_KEY = "YOUR_API_KEY"; const VIDEO_URL = "https://www.youtube.com/watch?v=dQw4w9WgXcQ"; const params = new URLSearchParams({ url: VIDEO_URL, quality: "audio" }); const response = await fetch(`https://api.huntapi.com/v1/video/download?${params}`, { headers: { "x-api-key": API_KEY }, }); const { job_id } = await response.json(); console.log(`Audio job submitted: ${job_id}`); ``` ```php $videoUrl, "quality" => "audio"]); $ch = curl_init("https://api.huntapi.com/v1/video/download?{$params}"); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_HTTPHEADER, ["x-api-key: {$apiKey}"]); $data = json_decode(curl_exec($ch), true); curl_close($ch); $jobId = $data["job_id"]; echo "Audio job submitted: {$jobId}\n"; ``` ```go package main import ( "encoding/json" "fmt" "io" "net/http" "net/url" "os" "time" ) const ( APIKey = "YOUR_API_KEY" VideoURL = "https://www.youtube.com/watch?v=dQw4w9WgXcQ" ) func get(apiKey, rawURL string) map[string]any { req, _ := http.NewRequest("GET", rawURL, nil) req.Header.Set("x-api-key", apiKey) resp, _ := http.DefaultClient.Do(req) defer resp.Body.Close() body, _ := io.ReadAll(resp.Body) var m map[string]any json.Unmarshal(body, &m) return m } func main() { params := url.Values{"url": {VideoURL}, "quality": {"audio"}} data := get(APIKey, "https://api.huntapi.com/v1/video/download?"+params.Encode()) jobID := data["job_id"].(string) fmt.Println("Audio job submitted:", jobID) // polling in next step... } ``` ```java import java.net.URI; import java.net.URLEncoder; import java.net.http.*; import java.nio.charset.StandardCharsets; import org.json.*; var apiKey = "YOUR_API_KEY"; var videoUrl = URLEncoder.encode("https://www.youtube.com/watch?v=dQw4w9WgXcQ", StandardCharsets.UTF_8); var client = HttpClient.newHttpClient(); var req = HttpRequest.newBuilder() .uri(URI.create("https://api.huntapi.com/v1/video/download?url=" + videoUrl + "&quality=audio")) .header("x-api-key", apiKey).GET().build(); var resp = client.send(req, HttpResponse.BodyHandlers.ofString()); var jobId = new JSONObject(resp.body()).getString("job_id"); System.out.println("Audio job submitted: " + jobId); ``` ```csharp using System.Net.Http; using System.Text.Json; var apiKey = "YOUR_API_KEY"; var videoUrl = Uri.EscapeDataString("https://www.youtube.com/watch?v=dQw4w9WgXcQ"); using var client = new HttpClient(); client.DefaultRequestHeaders.Add("x-api-key", apiKey); var body = await client.GetStringAsync($"https://api.huntapi.com/v1/video/download?url={videoUrl}&quality=audio"); var jobId = JsonDocument.Parse(body).RootElement.GetProperty("job_id").GetString()!; Console.WriteLine($"Audio job submitted: {jobId}"); ``` ```rust use reqwest::Client; use serde_json::Value; #[tokio::main] async fn main() -> Result<(), reqwest::Error> { let client = Client::new(); let api_key = "YOUR_API_KEY"; let video_url = "https://www.youtube.com/watch?v=dQw4w9WgXcQ"; let data = client.get("https://api.huntapi.com/v1/video/download") .header("x-api-key", api_key) .query(&[("url", video_url), ("quality", "audio")]) .send().await?.json::().await?; let job_id = data["job_id"].as_str().unwrap(); println!("Audio job submitted: {}", job_id); Ok(()) } ``` Poll for completion [#poll-for-completion] Check the job status every 5 seconds until `status == "done"`. ```python import time def wait_for_job(job_id: str) -> dict: for _ in range(60): r = requests.get(f"https://api.huntapi.com/v1/job/{job_id}", headers={"x-api-key": API_KEY}) result = r.json() status = result["status"] print(f" [{status}]") if status == "done": return result if status == "error": raise RuntimeError(result.get("error", "Unknown error")) time.sleep(5) raise TimeoutError("Job timed out") result = wait_for_job(job_id) download_url = result["download_url"] ``` ```typescript async function waitForJob(jobId: string) { for (let i = 0; i < 60; i++) { const res = await fetch(`https://api.huntapi.com/v1/job/${jobId}`, { headers: { "x-api-key": API_KEY }, }); const result = await res.json(); console.log(` [${result.status}]`); if (result.status === "done") return result; if (result.status === "error") throw new Error(result.error ?? "Unknown error"); await new Promise(r => setTimeout(r, 5000)); } throw new Error("Timeout"); } const result = await waitForJob(job_id); const downloadUrl = result.download_url; ``` ```php function waitForJob(string $apiKey, string $jobId): array { for ($i = 0; $i < 60; $i++) { $ch = curl_init("https://api.huntapi.com/v1/job/{$jobId}"); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_HTTPHEADER, ["x-api-key: {$apiKey}"]); $result = json_decode(curl_exec($ch), true); curl_close($ch); $status = $result["status"] ?? ""; echo " [{$status}]\n"; if ($status === "done") return $result; if ($status === "error") throw new RuntimeException($result["error"] ?? "Unknown"); sleep(5); } throw new RuntimeException("Timeout"); } $result = waitForJob($apiKey, $jobId); $downloadUrl = $result["download_url"]; ``` ```go func waitForJob(apiKey, jobID string) string { for i := 0; i < 60; i++ { data := get(apiKey, "https://api.huntapi.com/v1/job/"+jobID) status := data["status"].(string) fmt.Printf(" [%s]\n", status) if status == "done" { return data["download_url"].(string) } if status == "error" { panic("Job failed: " + fmt.Sprint(data["error"])) } time.Sleep(5 * time.Second) } panic("Timeout") } downloadURL := waitForJob(APIKey, jobID) ``` ```java static String waitForJob(HttpClient client, String apiKey, String jobId) throws Exception { for (int i = 0; i < 60; i++) { var req = HttpRequest.newBuilder() .uri(URI.create("https://api.huntapi.com/v1/job/" + jobId)) .header("x-api-key", apiKey).GET().build(); var resp = client.send(req, HttpResponse.BodyHandlers.ofString()); var result = new JSONObject(resp.body()); var status = result.getString("status"); System.out.println(" [" + status + "]"); if ("done".equals(status)) return result.getString("download_url"); if ("error".equals(status)) throw new RuntimeException(result.optString("error")); Thread.sleep(5000); } throw new RuntimeException("Timeout"); } var downloadUrl = waitForJob(client, apiKey, jobId); ``` ```csharp async Task WaitForJob(HttpClient client, string jobId) { for (int i = 0; i < 60; i++) { var body = await client.GetStringAsync($"https://api.huntapi.com/v1/job/{jobId}"); var result = JsonDocument.Parse(body).RootElement; var status = result.GetProperty("status").GetString(); Console.WriteLine($" [{status}]"); if (status == "done") return result.GetProperty("download_url").GetString()!; if (status == "error") throw new Exception(result.GetProperty("error").GetString()); await Task.Delay(5000); } throw new TimeoutException(); } var downloadUrl = await WaitForJob(client, jobId); ``` ```rust use tokio::time::{sleep, Duration}; async fn wait_for_job(client: &Client, api_key: &str, job_id: &str) -> String { for _ in 0..60 { let result = client.get(format!("https://api.huntapi.com/v1/job/{}", job_id)) .header("x-api-key", api_key) .send().await.unwrap().json::().await.unwrap(); let status = result["status"].as_str().unwrap_or(""); println!(" [{}]", status); if status == "done" { return result["download_url"].as_str().unwrap().to_string(); } if status == "error" { panic!("Job failed: {}", result["error"]); } sleep(Duration::from_secs(5)).await; } panic!("Timeout") } ``` Save the audio file [#save-the-audio-file] Download the MP3 and save it to disk. ```python output_file = "audio.mp3" with requests.get(download_url, stream=True) as r: r.raise_for_status() with open(output_file, "wb") as f: for chunk in r.iter_content(chunk_size=8192): f.write(chunk) print(f"Audio saved to {output_file} ({os.path.getsize(output_file) // 1024} KB)") ``` ```typescript import { createWriteStream } from "fs"; import { Readable } from "stream"; const fileRes = await fetch(downloadUrl); const writer = createWriteStream("audio.mp3"); Readable.fromWeb(fileRes.body as any).pipe(writer); await new Promise((resolve, reject) => { writer.on("finish", resolve); writer.on("error", reject); }); console.log("Audio saved to audio.mp3"); ``` ```php $fp = fopen("audio.mp3", "wb"); $ch = curl_init($downloadUrl); curl_setopt($ch, CURLOPT_FILE, $fp); curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true); curl_exec($ch); curl_close($ch); fclose($fp); echo "Audio saved to audio.mp3\n"; ``` ```go resp, _ := http.Get(downloadURL) defer resp.Body.Close() file, _ := os.Create("audio.mp3") defer file.Close() io.Copy(file, resp.Body) fmt.Println("Audio saved to audio.mp3") ``` ```java import java.net.URL; import java.nio.file.*; Files.copy(new URL(downloadUrl).openStream(), Path.of("audio.mp3"), StandardCopyOption.REPLACE_EXISTING); System.out.println("Audio saved to audio.mp3"); ``` ```csharp using var audioStream = await new HttpClient().GetStreamAsync(downloadUrl); using var file = File.Create("audio.mp3"); await audioStream.CopyToAsync(file); Console.WriteLine("Audio saved to audio.mp3"); ``` ```rust use std::{fs::File, io::Write}; let bytes = reqwest::get(download_url).await?.bytes().await?; let mut file = File::create("audio.mp3").unwrap(); file.write_all(&bytes).unwrap(); println!("Audio saved to audio.mp3"); ``` The extracted audio is delivered as an MP3. You can pipe it directly to a transcription service (e.g. OpenAI Whisper or Deepgram) for automatic subtitling or search indexing. # Download Your First Video Overview [#overview] HuntAPI uses an **asynchronous job model**: you submit a URL, receive a `job_id`, then poll until the video is ready. This playbook walks through all three steps and downloads the finished file to disk. Prerequisites [#prerequisites] * A HuntAPI key — get one at [app.huntapi.com](https://app.huntapi.com) * Install dependencies for your language: ```bash pip install requests ``` No extra dependencies — uses the native `fetch` API (Node 18+). `curl` extension enabled (on by default). No extra dependencies — uses `net/http` (Go 1.18+). No extra dependencies — uses `java.net.http` (Java 11+). No extra dependencies — uses `System.Net.Http` (.NET 6+). ```toml # Cargo.toml [dependencies] reqwest = { version = "0.12", features = ["json", "stream"] } tokio = { version = "1", features = ["full"] } serde_json = "1" ``` Steps [#steps] Submit the download job [#submit-the-download-job] Call `GET /v1/video/download` with the `url` parameter. The response immediately returns a `job_id`. ```python import requests API_KEY = "YOUR_API_KEY" VIDEO_URL = "https://www.youtube.com/watch?v=dQw4w9WgXcQ" response = requests.get( "https://api.huntapi.com/v1/video/download", headers={"x-api-key": API_KEY}, params={"url": VIDEO_URL, "quality": "best"}, ) data = response.json() job_id = data["job_id"] print(f"Job submitted: {job_id}") ``` ```typescript const API_KEY = "YOUR_API_KEY"; const VIDEO_URL = "https://www.youtube.com/watch?v=dQw4w9WgXcQ"; const params = new URLSearchParams({ url: VIDEO_URL, quality: "best" }); const response = await fetch(`https://api.huntapi.com/v1/video/download?${params}`, { headers: { "x-api-key": API_KEY }, }); const data = await response.json(); const jobId = data.job_id; console.log(`Job submitted: ${jobId}`); ``` ```php $videoUrl, "quality" => "best"]); $ch = curl_init("https://api.huntapi.com/v1/video/download?{$params}"); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_HTTPHEADER, ["x-api-key: {$apiKey}"]); $data = json_decode(curl_exec($ch), true); curl_close($ch); $jobId = $data["job_id"]; echo "Job submitted: {$jobId}\n"; ``` ```go package main import ( "encoding/json" "fmt" "io" "net/http" "net/url" ) const APIKey = "YOUR_API_KEY" const VideoURL = "https://www.youtube.com/watch?v=dQw4w9WgXcQ" func main() { params := url.Values{"url": {VideoURL}, "quality": {"best"}} req, _ := http.NewRequest("GET", "https://api.huntapi.com/v1/video/download?"+params.Encode(), nil) req.Header.Set("x-api-key", APIKey) resp, _ := http.DefaultClient.Do(req) defer resp.Body.Close() body, _ := io.ReadAll(resp.Body) var data map[string]any json.Unmarshal(body, &data) jobID := data["job_id"].(string) fmt.Println("Job submitted:", jobID) // continue in next step... } ``` ```java import java.net.URI; import java.net.URLEncoder; import java.net.http.*; import java.nio.charset.StandardCharsets; import org.json.*; var apiKey = "YOUR_API_KEY"; var videoUrl = URLEncoder.encode("https://www.youtube.com/watch?v=dQw4w9WgXcQ", StandardCharsets.UTF_8); var url = "https://api.huntapi.com/v1/video/download?url=" + videoUrl + "&quality=best"; var client = HttpClient.newHttpClient(); var request = HttpRequest.newBuilder().uri(URI.create(url)) .header("x-api-key", apiKey).GET().build(); var response = client.send(request, HttpResponse.BodyHandlers.ofString()); var jobId = new JSONObject(response.body()).getString("job_id"); System.out.println("Job submitted: " + jobId); ``` ```csharp using System.Net.Http; using System.Text.Json; var apiKey = "YOUR_API_KEY"; var videoUrl = Uri.EscapeDataString("https://www.youtube.com/watch?v=dQw4w9WgXcQ"); using var client = new HttpClient(); client.DefaultRequestHeaders.Add("x-api-key", apiKey); var body = await client.GetStringAsync($"https://api.huntapi.com/v1/video/download?url={videoUrl}&quality=best"); var jobId = JsonDocument.Parse(body).RootElement.GetProperty("job_id").GetString()!; Console.WriteLine($"Job submitted: {jobId}"); ``` ```rust use reqwest::Client; use serde_json::Value; let client = Client::new(); let api_key = "YOUR_API_KEY"; let video_url = "https://www.youtube.com/watch?v=dQw4w9WgXcQ"; let data = client.get("https://api.huntapi.com/v1/video/download") .header("x-api-key", api_key) .query(&[("url", video_url), ("quality", "best")]) .send().await?.json::().await?; let job_id = data["job_id"].as_str().unwrap(); println!("Job submitted: {}", job_id); ``` Poll until the video is ready [#poll-until-the-video-is-ready] Check `GET /v1/job/{job_id}` every few seconds. When `status` becomes `"done"`, the `download_url` field contains the file URL. ```python import time def wait_for_job(job_id: str, poll_interval: int = 5, timeout: int = 300) -> dict: start = time.time() while time.time() - start < timeout: r = requests.get(f"https://api.huntapi.com/v1/job/{job_id}", headers={"x-api-key": API_KEY}) result = r.json() status = result.get("status") print(f" Status: {status}") if status == "done": return result if status == "error": raise RuntimeError(f"Job failed: {result.get('error')}") time.sleep(poll_interval) raise TimeoutError("Job did not complete within the timeout period.") result = wait_for_job(job_id) download_url = result["download_url"] print(f"Ready! Download URL: {download_url}") ``` ```typescript async function waitForJob(jobId: string, pollMs = 5000, timeoutMs = 300_000) { const deadline = Date.now() + timeoutMs; while (Date.now() < deadline) { const res = await fetch(`https://api.huntapi.com/v1/job/${jobId}`, { headers: { "x-api-key": API_KEY }, }); const result = await res.json(); console.log(` Status: ${result.status}`); if (result.status === "done") return result; if (result.status === "error") throw new Error(`Job failed: ${result.error}`); await new Promise(r => setTimeout(r, pollMs)); } throw new Error("Timeout"); } const result = await waitForJob(jobId); const downloadUrl = result.download_url; console.log(`Ready! Download URL: ${downloadUrl}`); ``` ```php function waitForJob(string $apiKey, string $jobId, int $pollSec = 5, int $timeoutSec = 300): array { $start = time(); while (time() - $start < $timeoutSec) { $ch = curl_init("https://api.huntapi.com/v1/job/{$jobId}"); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_HTTPHEADER, ["x-api-key: {$apiKey}"]); $result = json_decode(curl_exec($ch), true); curl_close($ch); $status = $result["status"] ?? ""; echo " Status: {$status}\n"; if ($status === "done") return $result; if ($status === "error") throw new RuntimeException("Job failed: " . ($result["error"] ?? "")); sleep($pollSec); } throw new RuntimeException("Timeout"); } $result = waitForJob($apiKey, $jobId); $downloadUrl = $result["download_url"]; echo "Ready! Download URL: {$downloadUrl}\n"; ``` ```go import "time" func waitForJob(apiKey, jobID string) (map[string]any, error) { deadline := time.Now().Add(5 * time.Minute) for time.Now().Before(deadline) { req, _ := http.NewRequest("GET", "https://api.huntapi.com/v1/job/"+jobID, nil) req.Header.Set("x-api-key", apiKey) resp, _ := http.DefaultClient.Do(req) body, _ := io.ReadAll(resp.Body) resp.Body.Close() var result map[string]any json.Unmarshal(body, &result) status := result["status"].(string) fmt.Println(" Status:", status) if status == "done" { return result, nil } if status == "error" { return nil, fmt.Errorf("job failed: %v", result["error"]) } time.Sleep(5 * time.Second) } return nil, fmt.Errorf("timeout") } result, err := waitForJob(APIKey, jobID) if err != nil { panic(err) } downloadURL := result["download_url"].(string) fmt.Println("Ready! Download URL:", downloadURL) ``` ```java import java.time.*; static JSONObject waitForJob(HttpClient client, String apiKey, String jobId) throws Exception { var deadline = Instant.now().plusSeconds(300); while (Instant.now().isBefore(deadline)) { var req = HttpRequest.newBuilder() .uri(URI.create("https://api.huntapi.com/v1/job/" + jobId)) .header("x-api-key", apiKey).GET().build(); var resp = client.send(req, HttpResponse.BodyHandlers.ofString()); var result = new JSONObject(resp.body()); var status = result.getString("status"); System.out.println(" Status: " + status); if ("done".equals(status)) return result; if ("error".equals(status)) throw new RuntimeException("Job failed: " + result.optString("error")); Thread.sleep(5000); } throw new RuntimeException("Timeout"); } var result = waitForJob(client, apiKey, jobId); var downloadUrl = result.getString("download_url"); System.out.println("Ready! Download URL: " + downloadUrl); ``` ```csharp async Task WaitForJob(HttpClient client, string jobId) { var deadline = DateTime.UtcNow.AddMinutes(5); while (DateTime.UtcNow < deadline) { var body = await client.GetStringAsync($"https://api.huntapi.com/v1/job/{jobId}"); var result = JsonDocument.Parse(body).RootElement; var status = result.GetProperty("status").GetString(); Console.WriteLine($" Status: {status}"); if (status == "done") return result; if (status == "error") throw new Exception($"Job failed: {result.GetProperty("error")}"); await Task.Delay(5000); } throw new TimeoutException("Job did not complete in time."); } var result = await WaitForJob(client, jobId); var downloadUrl = result.GetProperty("download_url").GetString()!; Console.WriteLine($"Ready! Download URL: {downloadUrl}"); ``` ```rust use tokio::time::{sleep, Duration}; use std::time::Instant; async fn wait_for_job(client: &Client, api_key: &str, job_id: &str) -> Value { let deadline = Instant::now() + Duration::from_secs(300); loop { assert!(Instant::now() < deadline, "Timeout"); let result = client.get(format!("https://api.huntapi.com/v1/job/{}", job_id)) .header("x-api-key", api_key) .send().await.unwrap().json::().await.unwrap(); let status = result["status"].as_str().unwrap_or(""); println!(" Status: {}", status); if status == "done" { return result; } if status == "error" { panic!("Job failed: {}", result["error"]); } sleep(Duration::from_secs(5)).await; } } let result = wait_for_job(&client, api_key, job_id).await; let download_url = result["download_url"].as_str().unwrap(); println!("Ready! Download URL: {}", download_url); ``` Download the video file to disk [#download-the-video-file-to-disk] Stream the file from the `download_url` and save it locally. ```python filename = "video.mp4" with requests.get(download_url, stream=True) as r: r.raise_for_status() with open(filename, "wb") as f: for chunk in r.iter_content(chunk_size=8192): f.write(chunk) print(f"Saved to {filename}") ``` ```typescript import { createWriteStream } from "fs"; import { Readable } from "stream"; const fileResponse = await fetch(downloadUrl); const writer = createWriteStream("video.mp4"); Readable.fromWeb(fileResponse.body as any).pipe(writer); await new Promise((resolve, reject) => { writer.on("finish", resolve); writer.on("error", reject); }); console.log("Saved to video.mp4"); ``` ```php $fp = fopen("video.mp4", "wb"); $ch = curl_init($downloadUrl); curl_setopt($ch, CURLOPT_FILE, $fp); curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true); curl_exec($ch); curl_close($ch); fclose($fp); echo "Saved to video.mp4\n"; ``` ```go import "os" resp, _ := http.Get(downloadURL) defer resp.Body.Close() file, _ := os.Create("video.mp4") defer file.Close() io.Copy(file, resp.Body) fmt.Println("Saved to video.mp4") ``` ```java import java.nio.file.*; import java.net.URL; var in = new URL(downloadUrl).openStream(); Files.copy(in, Path.of("video.mp4"), StandardCopyOption.REPLACE_EXISTING); System.out.println("Saved to video.mp4"); ``` ```csharp using var fileStream = File.Create("video.mp4"); using var download = await new HttpClient().GetStreamAsync(downloadUrl); await download.CopyToAsync(fileStream); Console.WriteLine("Saved to video.mp4"); ``` ```rust use std::io::Write; use std::fs::File; let bytes = reqwest::get(download_url).await?.bytes().await?; let mut file = File::create("video.mp4").unwrap(); file.write_all(&bytes).unwrap(); println!("Saved to video.mp4"); ``` You can pass `quality: "best"`, `"1080p"`, `"720p"`, or `"audio"` in the initial request to control the output format before the job is submitted. # Batch Downloads with Webhooks Overview [#overview] Instead of polling, you can pass a `webhook_url` when submitting a job. HuntAPI will POST the result to your URL the moment the download is ready. This playbook shows how to: 1. Submit a batch of jobs with a webhook URL 2. Receive and verify the webhook payload Prerequisites [#prerequisites] * A HuntAPI key — get one at [app.huntapi.com](https://app.huntapi.com) * A publicly reachable HTTP endpoint (use [ngrok](https://ngrok.com) for local testing) * Install dependencies for your language: ```bash pip install requests flask ``` ```bash npm install express @types/express ``` `curl` extension enabled (on by default). No extra dependencies — uses `net/http` (Go 1.18+). No extra dependencies — uses `com.sun.net.httpserver` (built-in, Java 6+). No extra dependencies — uses ASP.NET minimal API (.NET 6+). ```toml # Cargo.toml [dependencies] reqwest = { version = "0.12", features = ["json"] } tokio = { version = "1", features = ["full"] } serde_json = "1" axum = "0.7" ``` Steps [#steps] Submit a batch of jobs with a webhook URL [#submit-a-batch-of-jobs-with-a-webhook-url] Pass your publicly accessible endpoint as `webhook_url`. Each job is independent; HuntAPI will call the webhook when it finishes. ```python import requests API_KEY = "YOUR_API_KEY" WEBHOOK_URL = "https://yourserver.example.com/webhooks/huntapi" URLS = [ "https://www.youtube.com/watch?v=VIDEO_ID_1", "https://www.youtube.com/watch?v=VIDEO_ID_2", "https://www.youtube.com/watch?v=VIDEO_ID_3", ] job_ids = [] for video_url in URLS: r = requests.get( "https://api.huntapi.com/v1/video/download", headers={"x-api-key": API_KEY}, params={"url": video_url, "quality": "best", "webhook_url": WEBHOOK_URL}, ) job_id = r.json()["job_id"] job_ids.append(job_id) print(f"Submitted: {job_id}") print(f"\n{len(job_ids)} jobs submitted. Waiting for webhooks...") ``` ```typescript const API_KEY = "YOUR_API_KEY"; const WEBHOOK_URL = "https://yourserver.example.com/webhooks/huntapi"; const URLS = [ "https://www.youtube.com/watch?v=VIDEO_ID_1", "https://www.youtube.com/watch?v=VIDEO_ID_2", "https://www.youtube.com/watch?v=VIDEO_ID_3", ]; const jobIds: string[] = []; for (const videoUrl of URLS) { const params = new URLSearchParams({ url: videoUrl, quality: "best", webhook_url: WEBHOOK_URL }); const res = await fetch(`https://api.huntapi.com/v1/video/download?${params}`, { headers: { "x-api-key": API_KEY }, }); const { job_id } = await res.json(); jobIds.push(job_id); console.log(`Submitted: ${job_id}`); } console.log(`\n${jobIds.length} jobs submitted. Waiting for webhooks...`); ``` ```php $videoUrl, "quality" => "best", "webhook_url" => $webhookUrl]); $ch = curl_init("https://api.huntapi.com/v1/video/download?{$params}"); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_HTTPHEADER, ["x-api-key: {$apiKey}"]); $data = json_decode(curl_exec($ch), true); curl_close($ch); $jobIds[] = $data["job_id"]; echo "Submitted: {$data['job_id']}\n"; } echo count($jobIds) . " jobs submitted. Waiting for webhooks...\n"; ``` ```go package main import ( "encoding/json" "fmt" "io" "net/http" "net/url" ) func submitJob(apiKey, videoURL, webhookURL string) string { params := url.Values{"url": {videoURL}, "quality": {"best"}, "webhook_url": {webhookURL}} req, _ := http.NewRequest("GET", "https://api.huntapi.com/v1/video/download?"+params.Encode(), nil) req.Header.Set("x-api-key", apiKey) resp, _ := http.DefaultClient.Do(req) defer resp.Body.Close() body, _ := io.ReadAll(resp.Body) var data map[string]any json.Unmarshal(body, &data) return data["job_id"].(string) } func main() { apiKey := "YOUR_API_KEY" webhookURL := "https://yourserver.example.com/webhooks/huntapi" urls := []string{ "https://www.youtube.com/watch?v=VIDEO_ID_1", "https://www.youtube.com/watch?v=VIDEO_ID_2", "https://www.youtube.com/watch?v=VIDEO_ID_3", } for _, u := range urls { jobID := submitJob(apiKey, u, webhookURL) fmt.Println("Submitted:", jobID) } fmt.Printf("%d jobs submitted. Waiting for webhooks...\n", len(urls)) } ``` ```java import java.net.URI; import java.net.URLEncoder; import java.net.http.*; import java.nio.charset.StandardCharsets; import org.json.*; var client = HttpClient.newHttpClient(); var apiKey = "YOUR_API_KEY"; var webhookUrl = "https://yourserver.example.com/webhooks/huntapi"; var urls = new String[]{ "https://www.youtube.com/watch?v=VIDEO_ID_1", "https://www.youtube.com/watch?v=VIDEO_ID_2", "https://www.youtube.com/watch?v=VIDEO_ID_3", }; for (var videoUrl : urls) { var encoded = URLEncoder.encode(videoUrl, StandardCharsets.UTF_8); var wh = URLEncoder.encode(webhookUrl, StandardCharsets.UTF_8); var url = "https://api.huntapi.com/v1/video/download?url=" + encoded + "&quality=best&webhook_url=" + wh; var req = HttpRequest.newBuilder().uri(URI.create(url)) .header("x-api-key", apiKey).GET().build(); var resp = client.send(req, HttpResponse.BodyHandlers.ofString()); var jobId = new JSONObject(resp.body()).getString("job_id"); System.out.println("Submitted: " + jobId); } ``` ```csharp using System.Net.Http; using System.Text.Json; var apiKey = "YOUR_API_KEY"; var webhookUrl = Uri.EscapeDataString("https://yourserver.example.com/webhooks/huntapi"); using var client = new HttpClient(); client.DefaultRequestHeaders.Add("x-api-key", apiKey); var urls = new[] { "https://www.youtube.com/watch?v=VIDEO_ID_1", "https://www.youtube.com/watch?v=VIDEO_ID_2", "https://www.youtube.com/watch?v=VIDEO_ID_3", }; foreach (var videoUrl in urls) { var encoded = Uri.EscapeDataString(videoUrl); var body = await client.GetStringAsync( $"https://api.huntapi.com/v1/video/download?url={encoded}&quality=best&webhook_url={webhookUrl}"); var jobId = JsonDocument.Parse(body).RootElement.GetProperty("job_id").GetString(); Console.WriteLine($"Submitted: {jobId}"); } ``` ```rust use reqwest::Client; use serde_json::Value; #[tokio::main] async fn main() -> Result<(), reqwest::Error> { let client = Client::new(); let api_key = "YOUR_API_KEY"; let webhook_url = "https://yourserver.example.com/webhooks/huntapi"; let urls = [ "https://www.youtube.com/watch?v=VIDEO_ID_1", "https://www.youtube.com/watch?v=VIDEO_ID_2", "https://www.youtube.com/watch?v=VIDEO_ID_3", ]; for video_url in &urls { let data = client.get("https://api.huntapi.com/v1/video/download") .header("x-api-key", api_key) .query(&[("url", video_url), ("quality", &"best"), ("webhook_url", &webhook_url)]) .send().await?.json::().await?; println!("Submitted: {}", data["job_id"].as_str().unwrap_or("")); } Ok(()) } ``` Build a webhook receiver [#build-a-webhook-receiver] HuntAPI will POST a JSON body to your endpoint with `job_id`, `status`, and `download_url` when the job completes. ```python from flask import Flask, request, jsonify app = Flask(__name__) @app.route("/webhooks/huntapi", methods=["POST"]) def huntapi_webhook(): payload = request.get_json() job_id = payload.get("job_id") status = payload.get("status") download_url = payload.get("download_url") print(f"Webhook received — Job: {job_id}, Status: {status}") if status == "done" and download_url: # Trigger your download or further processing here print(f" Download URL: {download_url}") return jsonify({"received": True}), 200 if __name__ == "__main__": app.run(port=3000) ``` ```typescript import express from "express"; const app = express(); app.use(express.json()); app.post("/webhooks/huntapi", (req, res) => { const { job_id, status, download_url } = req.body; console.log(`Webhook received — Job: ${job_id}, Status: ${status}`); if (status === "done" && download_url) { // Trigger your download or further processing here console.log(` Download URL: ${download_url}`); } res.json({ received: true }); }); app.listen(3000, () => console.log("Webhook listener on :3000")); ``` ```php true]); ``` ```go package main import ( "encoding/json" "fmt" "net/http" ) func main() { http.HandleFunc("/webhooks/huntapi", func(w http.ResponseWriter, r *http.Request) { var payload map[string]any json.NewDecoder(r.Body).Decode(&payload) jobID := payload["job_id"] status := payload["status"] downloadURL := payload["download_url"] fmt.Printf("Webhook received — Job: %v, Status: %v\n", jobID, status) if status == "done" && downloadURL != nil { fmt.Println(" Download URL:", downloadURL) // Trigger download or further processing here } w.Header().Set("Content-Type", "application/json") w.Write([]byte(`{"received":true}`)) }) fmt.Println("Webhook listener on :3000") http.ListenAndServe(":3000", nil) } ``` ```java import com.sun.net.httpserver.*; import java.net.InetSocketAddress; import org.json.*; public class WebhookServer { public static void main(String[] args) throws Exception { var server = HttpServer.create(new InetSocketAddress(3000), 0); server.createContext("/webhooks/huntapi", exchange -> { var body = exchange.getRequestBody().readAllBytes(); var payload = new JSONObject(new String(body)); var jobId = payload.optString("job_id"); var status = payload.optString("status"); var downloadUrl = payload.optString("download_url"); System.out.printf("Webhook received — Job: %s, Status: %s%n", jobId, status); if ("done".equals(status) && !downloadUrl.isEmpty()) { System.out.println(" Download URL: " + downloadUrl); } var resp = "{\"received\":true}".getBytes(); exchange.sendResponseHeaders(200, resp.length); exchange.getResponseBody().write(resp); exchange.close(); }); server.start(); System.out.println("Webhook listener on :3000"); } } ``` ```csharp using System.Text.Json; var app = WebApplication.Create(); app.MapPost("/webhooks/huntapi", async (HttpContext ctx) => { using var reader = new StreamReader(ctx.Request.Body); var body = await reader.ReadToEndAsync(); var payload = JsonDocument.Parse(body).RootElement; var jobId = payload.GetProperty("job_id").GetString(); var status = payload.GetProperty("status").GetString(); var downloadUrl = payload.TryGetProperty("download_url", out var d) ? d.GetString() : null; Console.WriteLine($"Webhook received — Job: {jobId}, Status: {status}"); if (status == "done" && downloadUrl != null) Console.WriteLine($" Download URL: {downloadUrl}"); return Results.Json(new { received = true }); }); Console.WriteLine("Webhook listener on :3000"); app.Run("http://0.0.0.0:3000"); ``` ```rust use axum::{extract::Json as AxumJson, routing::post, Router}; use serde_json::{json, Value}; async fn huntapi_webhook(AxumJson(payload): AxumJson) -> AxumJson { let job_id = payload["job_id"].as_str().unwrap_or(""); let status = payload["status"].as_str().unwrap_or(""); let download_url = payload["download_url"].as_str().unwrap_or(""); println!("Webhook received — Job: {}, Status: {}", job_id, status); if status == "done" && !download_url.is_empty() { println!(" Download URL: {}", download_url); } AxumJson(json!({ "received": true })) } #[tokio::main] async fn main() { let app = Router::new().route("/webhooks/huntapi", post(huntapi_webhook)); let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap(); println!("Webhook listener on :3000"); axum::serve(listener, app).await.unwrap(); } ``` Test locally with ngrok [#test-locally-with-ngrok] During development, use ngrok to expose your local server to the internet so HuntAPI can reach your webhook. ```bash # Start your local server first, then: ngrok http 3000 ``` Copy the generated `https://xxxx.ngrok.io` URL and use it as your `webhook_url` parameter. Your webhook endpoint must return a `2xx` status code within 10 seconds, otherwise HuntAPI will retry the delivery. Make heavy processing asynchronous and acknowledge the webhook immediately. # Find a Professional Email Overview [#overview] This playbook shows how to find and verify a professional email address for a prospect. Use it in outbound sales pipelines to auto-enrich contact records before sending a sequence. Prerequisites [#prerequisites] * A Piloterr API key — get one at [app.piloterr.com](https://app.piloterr.com) * Install dependencies for your language: ```bash pip install requests ``` No extra dependencies — uses the native `fetch` API (Node 18+). `curl` extension enabled (on by default). No extra dependencies — uses `net/http` (Go 1.18+). No extra dependencies — uses `java.net.http` (Java 11+). No extra dependencies — uses `System.Net.Http` (.NET 6+). ```toml # Cargo.toml [dependencies] reqwest = { version = "0.12", features = ["json"] } tokio = { version = "1", features = ["full"] } serde_json = "1" ``` Steps [#steps] Find an email address [#find-an-email-address] Call `GET /v2/email/finder` with `first_name`, `last_name`, and `domain`. ```python import requests API_KEY = "YOUR_API_KEY" response = requests.get( "https://api.piloterr.com/v2/email/finder", headers={"x-api-key": API_KEY}, params={"first_name": "Patrick", "last_name": "Collison", "domain": "stripe.com"}, ) result = response.json() print(result) ``` ```typescript const API_KEY = "YOUR_API_KEY"; const params = new URLSearchParams({ first_name: "Patrick", last_name: "Collison", domain: "stripe.com" }); const response = await fetch(`https://api.piloterr.com/v2/email/finder?${params}`, { headers: { "x-api-key": API_KEY }, }); const result = await response.json(); console.log(result); ``` ```php "Patrick", "last_name" => "Collison", "domain" => "stripe.com"]); $ch = curl_init("https://api.piloterr.com/v2/email/finder?{$params}"); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_HTTPHEADER, ["x-api-key: {$apiKey}"]); $result = json_decode(curl_exec($ch), true); curl_close($ch); print_r($result); ``` ```go package main import ( "encoding/json" "fmt" "io" "net/http" "net/url" ) func main() { params := url.Values{ "first_name": {"Patrick"}, "last_name": {"Collison"}, "domain": {"stripe.com"}, } req, _ := http.NewRequest("GET", "https://api.piloterr.com/v2/email/finder?"+params.Encode(), nil) req.Header.Set("x-api-key", "YOUR_API_KEY") resp, _ := http.DefaultClient.Do(req) defer resp.Body.Close() body, _ := io.ReadAll(resp.Body) var result map[string]any json.Unmarshal(body, &result) fmt.Println(result) } ``` ```java import java.net.URI; import java.net.http.*; var client = HttpClient.newHttpClient(); var request = HttpRequest.newBuilder() .uri(URI.create("https://api.piloterr.com/v2/email/finder?first_name=Patrick&last_name=Collison&domain=stripe.com")) .header("x-api-key", "YOUR_API_KEY") .GET().build(); var response = client.send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.body()); ``` ```csharp using System.Net.Http; using var client = new HttpClient(); client.DefaultRequestHeaders.Add("x-api-key", "YOUR_API_KEY"); var body = await client.GetStringAsync( "https://api.piloterr.com/v2/email/finder?first_name=Patrick&last_name=Collison&domain=stripe.com"); Console.WriteLine(body); ``` ```rust #[tokio::main] async fn main() -> Result<(), reqwest::Error> { let result = reqwest::Client::new() .get("https://api.piloterr.com/v2/email/finder") .header("x-api-key", "YOUR_API_KEY") .query(&[("first_name", "Patrick"), ("last_name", "Collison"), ("domain", "stripe.com")]) .send().await?.json::().await?; println!("{:#?}", result); Ok(()) } ``` Inspect the result [#inspect-the-result] The response includes `email`, `confidence` (0–100), `status` (`valid`, `risky`, `invalid`), and the detected email pattern. ```python email = result.get("email") confidence = result.get("confidence") status = result.get("status") if email and confidence >= 70: print(f"✓ Found: {email} (confidence: {confidence}%, status: {status})") else: print(f"✗ Email not found or low confidence (status: {status})") ``` ```typescript const { email, confidence, status } = result; if (email && confidence >= 70) { console.log(`✓ Found: ${email} (confidence: ${confidence}%, status: ${status})`); } else { console.log(`✗ Email not found or low confidence (status: ${status})`); } ``` ```php $email = $result["email"] ?? null; $confidence = $result["confidence"] ?? 0; $status = $result["status"] ?? "unknown"; if ($email && $confidence >= 70) { echo "✓ Found: {$email} (confidence: {$confidence}%, status: {$status})\n"; } else { echo "✗ Email not found or low confidence (status: {$status})\n"; } ``` ```go email := result["email"] confidence := result["confidence"] status := result["status"] if email != nil && confidence.(float64) >= 70 { fmt.Printf("✓ Found: %v (confidence: %.0f%%, status: %v)\n", email, confidence, status) } else { fmt.Printf("✗ Email not found or low confidence (status: %v)\n", status) } ``` ```java import org.json.*; var r = new JSONObject(response.body()); var email = r.optString("email", null); var confidence = r.optInt("confidence", 0); var status = r.optString("status", "unknown"); if (email != null && confidence >= 70) { System.out.printf("✓ Found: %s (confidence: %d%%, status: %s)%n", email, confidence, status); } else { System.out.printf("✗ Email not found or low confidence (status: %s)%n", status); } ``` ```csharp using System.Text.Json; var r = JsonDocument.Parse(body).RootElement; var email = r.TryGetProperty("email", out var e) ? e.GetString() : null; var confidence = r.TryGetProperty("confidence", out var c) ? c.GetInt32() : 0; var status = r.TryGetProperty("status", out var s) ? s.GetString() : "unknown"; if (email != null && confidence >= 70) Console.WriteLine($"✓ Found: {email} (confidence: {confidence}%, status: {status})"); else Console.WriteLine($"✗ Email not found or low confidence (status: {status})"); ``` ```rust let email = result["email"].as_str().unwrap_or(""); let confidence = result["confidence"].as_i64().unwrap_or(0); let status = result["status"].as_str().unwrap_or("unknown"); if !email.is_empty() && confidence >= 70 { println!("✓ Found: {} (confidence: {}%, status: {})", email, confidence, status); } else { println!("✗ Email not found or low confidence (status: {})", status); } ``` Enrich a list of prospects from a CSV [#enrich-a-list-of-prospects-from-a-csv] Load a CSV of prospects, find their emails, and write results back out. ```python import csv, time, requests API_KEY = "YOUR_API_KEY" def find_email(first: str, last: str, domain: str) -> dict: r = requests.get("https://api.piloterr.com/v2/email/finder", headers={"x-api-key": API_KEY}, params={"first_name": first, "last_name": last, "domain": domain}) return r.json() prospects = [ {"first_name": "Patrick", "last_name": "Collison", "domain": "stripe.com"}, {"first_name": "Sam", "last_name": "Altman", "domain": "openai.com"}, {"first_name": "Tobi", "last_name": "Lutke", "domain": "shopify.com"}, ] with open("prospects_enriched.csv", "w", newline="") as f: fieldnames = ["first_name", "last_name", "domain", "email", "confidence", "status"] writer = csv.DictWriter(f, fieldnames=fieldnames) writer.writeheader() for p in prospects: result = find_email(p["first_name"], p["last_name"], p["domain"]) writer.writerow({**p, "email": result.get("email", ""), "confidence": result.get("confidence", 0), "status": result.get("status", "")}) time.sleep(0.5) print("Done! Results saved to prospects_enriched.csv") ``` ```typescript import { createWriteStream } from "fs"; const API_KEY = "YOUR_API_KEY"; const prospects = [ { first_name: "Patrick", last_name: "Collison", domain: "stripe.com" }, { first_name: "Sam", last_name: "Altman", domain: "openai.com" }, { first_name: "Tobi", last_name: "Lutke", domain: "shopify.com" }, ]; const rows: string[] = ["first_name,last_name,domain,email,confidence,status"]; for (const p of prospects) { const params = new URLSearchParams({ first_name: p.first_name, last_name: p.last_name, domain: p.domain }); const res = await fetch(`https://api.piloterr.com/v2/email/finder?${params}`, { headers: { "x-api-key": API_KEY }, }); const r = await res.json(); rows.push(`${p.first_name},${p.last_name},${p.domain},${r.email ?? ""},${r.confidence ?? 0},${r.status ?? ""}`); await new Promise(resolve => setTimeout(resolve, 500)); } import { writeFileSync } from "fs"; writeFileSync("prospects_enriched.csv", rows.join("\n")); console.log("Done! Results saved to prospects_enriched.csv"); ``` ```php "Patrick", "last_name" => "Collison", "domain" => "stripe.com"], ["first_name" => "Sam", "last_name" => "Altman", "domain" => "openai.com"], ["first_name" => "Tobi", "last_name" => "Lutke", "domain" => "shopify.com"], ]; $fp = fopen("prospects_enriched.csv", "w"); fputcsv($fp, ["first_name", "last_name", "domain", "email", "confidence", "status"]); foreach ($prospects as $p) { $params = http_build_query(array_merge($p, ["q" => ""])); $ch = curl_init("https://api.piloterr.com/v2/email/finder?" . http_build_query($p)); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_HTTPHEADER, ["x-api-key: {$apiKey}"]); $r = json_decode(curl_exec($ch), true); curl_close($ch); fputcsv($fp, [$p["first_name"], $p["last_name"], $p["domain"], $r["email"] ?? "", $r["confidence"] ?? 0, $r["status"] ?? ""]); usleep(500000); } fclose($fp); echo "Done! Results saved to prospects_enriched.csv\n"; ``` ```go package main import ( "encoding/csv" "encoding/json" "io" "net/http" "net/url" "os" "strconv" "time" ) type Prospect struct{ FirstName, LastName, Domain string } func findEmail(apiKey string, p Prospect) map[string]any { params := url.Values{"first_name": {p.FirstName}, "last_name": {p.LastName}, "domain": {p.Domain}} req, _ := http.NewRequest("GET", "https://api.piloterr.com/v2/email/finder?"+params.Encode(), nil) req.Header.Set("x-api-key", apiKey) resp, _ := http.DefaultClient.Do(req) defer resp.Body.Close() body, _ := io.ReadAll(resp.Body) var r map[string]any json.Unmarshal(body, &r) return r } func main() { apiKey := "YOUR_API_KEY" prospects := []Prospect{ {"Patrick", "Collison", "stripe.com"}, {"Sam", "Altman", "openai.com"}, {"Tobi", "Lutke", "shopify.com"}, } f, _ := os.Create("prospects_enriched.csv") w := csv.NewWriter(f) w.Write([]string{"first_name", "last_name", "domain", "email", "confidence", "status"}) for _, p := range prospects { r := findEmail(apiKey, p) confidence := strconv.FormatFloat(r["confidence"].(float64), 'f', 0, 64) w.Write([]string{p.FirstName, p.LastName, p.Domain, r["email"].(string), confidence, r["status"].(string)}) time.Sleep(500 * time.Millisecond) } w.Flush() f.Close() } ``` ```java import java.net.URI; import java.net.http.*; import java.nio.file.*; import java.util.*; import org.json.*; public class Main { public static void main(String[] args) throws Exception { var client = HttpClient.newHttpClient(); var apiKey = "YOUR_API_KEY"; var prospects = List.of( Map.of("first_name","Patrick","last_name","Collison","domain","stripe.com"), Map.of("first_name","Sam", "last_name","Altman", "domain","openai.com"), Map.of("first_name","Tobi", "last_name","Lutke", "domain","shopify.com")); var lines = new ArrayList(); lines.add("first_name,last_name,domain,email,confidence,status"); for (var p : prospects) { var url = "https://api.piloterr.com/v2/email/finder?first_name=" + p.get("first_name") + "&last_name=" + p.get("last_name") + "&domain=" + p.get("domain"); var req = HttpRequest.newBuilder().uri(URI.create(url)) .header("x-api-key", apiKey).GET().build(); var resp = client.send(req, HttpResponse.BodyHandlers.ofString()); var r = new JSONObject(resp.body()); lines.add(String.join(",", p.get("first_name"), p.get("last_name"), p.get("domain"), r.optString("email",""), String.valueOf(r.optInt("confidence")), r.optString("status",""))); Thread.sleep(500); } Files.write(Path.of("prospects_enriched.csv"), lines); System.out.println("Done! Results saved to prospects_enriched.csv"); } } ``` ```csharp using System.Net.Http; using System.Text.Json; using var client = new HttpClient(); client.DefaultRequestHeaders.Add("x-api-key", "YOUR_API_KEY"); var prospects = new[] { (first: "Patrick", last: "Collison", domain: "stripe.com"), (first: "Sam", last: "Altman", domain: "openai.com"), (first: "Tobi", last: "Lutke", domain: "shopify.com"), }; var lines = new List { "first_name,last_name,domain,email,confidence,status" }; foreach (var p in prospects) { var body = await client.GetStringAsync( $"https://api.piloterr.com/v2/email/finder?first_name={p.first}&last_name={p.last}&domain={p.domain}"); var r = JsonDocument.Parse(body).RootElement; var email = r.TryGetProperty("email", out var e) ? e.GetString() : ""; var confidence = r.TryGetProperty("confidence", out var c) ? c.GetInt32().ToString() : "0"; var status = r.TryGetProperty("status", out var s) ? s.GetString() : ""; lines.Add($"{p.first},{p.last},{p.domain},{email},{confidence},{status}"); await Task.Delay(500); } File.WriteAllLines("prospects_enriched.csv", lines); Console.WriteLine("Done! Results saved to prospects_enriched.csv"); ``` ```rust use reqwest::Client; use serde_json::Value; use std::{fs::File, io::Write, time::Duration}; use tokio::time::sleep; #[tokio::main] async fn main() -> Result<(), reqwest::Error> { let client = Client::new(); let api_key = "YOUR_API_KEY"; let prospects = vec![ ("Patrick", "Collison", "stripe.com"), ("Sam", "Altman", "openai.com"), ("Tobi", "Lutke", "shopify.com"), ]; let mut file = File::create("prospects_enriched.csv").unwrap(); writeln!(file, "first_name,last_name,domain,email,confidence,status").unwrap(); for (first, last, domain) in &prospects { let r = client.get("https://api.piloterr.com/v2/email/finder") .header("x-api-key", api_key) .query(&[("first_name", first), ("last_name", last), ("domain", domain)]) .send().await?.json::().await?; writeln!(file, "{},{},{},{},{},{}", first, last, domain, r["email"].as_str().unwrap_or(""), r["confidence"].as_i64().unwrap_or(0), r["status"].as_str().unwrap_or("")).unwrap(); sleep(Duration::from_millis(500)).await; } println!("Done! Results saved to prospects_enriched.csv"); Ok(()) } ``` Only use emails with `confidence >= 70` and `status == "valid"` in cold outreach. Lower-confidence addresses risk bounces that harm your domain reputation. # Enrich a Lead with LinkedIn Overview [#overview] This playbook builds a **CRM enrichment pipeline**: given a company's website domain, fetch its LinkedIn profile and extract structured data like industry, employee count, headquarters, and specialities. Prerequisites [#prerequisites] * A Piloterr API key — get one at [app.piloterr.com](https://app.piloterr.com) * Install dependencies for your language: ```bash pip install requests ``` No extra dependencies — uses the native `fetch` API (Node 18+). `curl` extension enabled (on by default in most PHP installs). No extra dependencies — uses `net/http` (Go 1.18+). No extra dependencies — uses `java.net.http` (Java 11+). No extra dependencies — uses `System.Net.Http` (.NET 6+). ```toml # Cargo.toml [dependencies] reqwest = { version = "0.12", features = ["json"] } tokio = { version = "1", features = ["full"] } serde_json = "1" ``` Steps [#steps] Look up a company by domain [#look-up-a-company-by-domain] Pass the company's website domain to the `domain` parameter. You can also use a LinkedIn URL via `query`. ```python import requests API_KEY = "YOUR_API_KEY" response = requests.get( "https://api.piloterr.com/v2/linkedin/company/info", headers={"x-api-key": API_KEY}, params={"domain": "stripe.com"}, ) company = response.json() print(company) ``` ```typescript const API_KEY = "YOUR_API_KEY"; const params = new URLSearchParams({ domain: "stripe.com" }); const response = await fetch(`https://api.piloterr.com/v2/linkedin/company/info?${params}`, { headers: { "x-api-key": API_KEY }, }); const company = await response.json(); console.log(company); ``` ```php "stripe.com"]); $ch = curl_init("https://api.piloterr.com/v2/linkedin/company/info?{$params}"); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_HTTPHEADER, ["x-api-key: {$apiKey}"]); $company = json_decode(curl_exec($ch), true); curl_close($ch); print_r($company); ``` ```go package main import ( "encoding/json" "fmt" "io" "net/http" ) func main() { req, _ := http.NewRequest("GET", "https://api.piloterr.com/v2/linkedin/company/info?domain=stripe.com", nil) req.Header.Set("x-api-key", "YOUR_API_KEY") resp, _ := http.DefaultClient.Do(req) defer resp.Body.Close() body, _ := io.ReadAll(resp.Body) var company map[string]any json.Unmarshal(body, &company) fmt.Println(company) } ``` ```java import java.net.URI; import java.net.http.*; var client = HttpClient.newHttpClient(); var request = HttpRequest.newBuilder() .uri(URI.create("https://api.piloterr.com/v2/linkedin/company/info?domain=stripe.com")) .header("x-api-key", "YOUR_API_KEY") .GET().build(); var response = client.send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.body()); ``` ```csharp using System.Net.Http; using var client = new HttpClient(); client.DefaultRequestHeaders.Add("x-api-key", "YOUR_API_KEY"); var body = await client.GetStringAsync( "https://api.piloterr.com/v2/linkedin/company/info?domain=stripe.com"); Console.WriteLine(body); ``` ```rust #[tokio::main] async fn main() -> Result<(), reqwest::Error> { let company = reqwest::Client::new() .get("https://api.piloterr.com/v2/linkedin/company/info") .header("x-api-key", "YOUR_API_KEY") .query(&[("domain", "stripe.com")]) .send().await?.json::().await?; println!("{:#?}", company); Ok(()) } ``` Extract key company fields [#extract-key-company-fields] The response contains `company_name`, `industry`, `staff_count`, `staff_range`, `tagline`, `description`, `headquarter`, and `specialities`. ```python print(f"Company : {company.get('company_name')}") print(f"Industry : {company.get('industry')}") print(f"Employees : {company.get('staff_count')} ({company.get('staff_range')})") print(f"Website : {company.get('website')}") hq = company.get("headquarter", {}) print(f"HQ : {hq.get('city')}, {hq.get('country')}") print(f"Topics : {', '.join(company.get('specialities', [])[:5])}") ``` ```typescript console.log(`Company : ${company.company_name}`); console.log(`Industry : ${company.industry}`); console.log(`Employees : ${company.staff_count} (${company.staff_range})`); console.log(`Website : ${company.website}`); console.log(`HQ : ${company.headquarter?.city}, ${company.headquarter?.country}`); console.log(`Topics : ${(company.specialities ?? []).slice(0, 5).join(", ")}`); ``` ```php echo "Company : {$company['company_name']}\n"; echo "Industry : {$company['industry']}\n"; echo "Employees : {$company['staff_count']} ({$company['staff_range']})\n"; echo "HQ : {$company['headquarter']['city']}, {$company['headquarter']['country']}\n"; echo "Topics : " . implode(", ", array_slice($company["specialities"] ?? [], 0, 5)) . "\n"; ``` ```go c := company fmt.Printf("Company : %v\nIndustry : %v\nEmployees : %v (%v)\nWebsite : %v\n", c["company_name"], c["industry"], c["staff_count"], c["staff_range"], c["website"]) if hq, ok := c["headquarter"].(map[string]any); ok { fmt.Printf("HQ : %v, %v\n", hq["city"], hq["country"]) } ``` ```java import org.json.*; var c = new JSONObject(response.body()); System.out.printf("Company : %s%nIndustry : %s%nEmployees : %d (%s)%nWebsite : %s%n", c.getString("company_name"), c.getString("industry"), c.getInt("staff_count"), c.getString("staff_range"), c.getString("website")); var hq = c.optJSONObject("headquarter"); if (hq != null) System.out.printf("HQ : %s, %s%n", hq.getString("city"), hq.getString("country")); ``` ```csharp using System.Text.Json; var c = JsonDocument.Parse(body).RootElement; Console.WriteLine($"Company : {c.GetProperty("company_name")}"); Console.WriteLine($"Industry : {c.GetProperty("industry")}"); Console.WriteLine($"Employees : {c.GetProperty("staff_count")} ({c.GetProperty("staff_range")})"); Console.WriteLine($"Website : {c.GetProperty("website")}"); var hq = c.GetProperty("headquarter"); Console.WriteLine($"HQ : {hq.GetProperty("city")}, {hq.GetProperty("country")}"); ``` ```rust let c = &company; println!("Company : {}", c["company_name"].as_str().unwrap_or("")); println!("Industry : {}", c["industry"].as_str().unwrap_or("")); println!("Employees : {} ({})", c["staff_count"], c["staff_range"].as_str().unwrap_or("")); println!("HQ : {}, {}", c["headquarter"]["city"].as_str().unwrap_or(""), c["headquarter"]["country"].as_str().unwrap_or("")); ``` Enrich a batch of leads [#enrich-a-batch-of-leads] Loop over a list of email domains and build enriched company records ready to push to your CRM. ```python import json, time, requests API_KEY = "YOUR_API_KEY" leads = [ {"email": "alice@stripe.com", "domain": "stripe.com"}, {"email": "bob@notion.so", "domain": "notion.so"}, {"email": "carol@figma.com", "domain": "figma.com"}, ] enriched = [] for lead in leads: r = requests.get("https://api.piloterr.com/v2/linkedin/company/info", headers={"x-api-key": API_KEY}, params={"domain": lead["domain"]}) if r.status_code == 200: c = r.json() enriched.append({"email": lead["email"], "domain": lead["domain"], "company": c.get("company_name"), "industry": c.get("industry"), "employees": c.get("staff_count"), "hq_country": c.get("headquarter", {}).get("country"), "linkedin_url": c.get("company_url")}) time.sleep(0.5) with open("enriched_leads.json", "w") as f: json.dump(enriched, f, indent=2) print(f"Enriched {len(enriched)} leads → enriched_leads.json") ``` ```typescript import { writeFileSync } from "fs"; const API_KEY = "YOUR_API_KEY"; const leads = [ { email: "alice@stripe.com", domain: "stripe.com" }, { email: "bob@notion.so", domain: "notion.so" }, { email: "carol@figma.com", domain: "figma.com" }, ]; const enriched: any[] = []; for (const lead of leads) { const params = new URLSearchParams({ domain: lead.domain }); const res = await fetch(`https://api.piloterr.com/v2/linkedin/company/info?${params}`, { headers: { "x-api-key": API_KEY }, }); if (res.ok) { const c = await res.json(); enriched.push({ email: lead.email, domain: lead.domain, company: c.company_name, industry: c.industry, employees: c.staff_count, hq_country: c.headquarter?.country, linkedin_url: c.company_url }); } await new Promise(r => setTimeout(r, 500)); } writeFileSync("enriched_leads.json", JSON.stringify(enriched, null, 2)); console.log(`Enriched ${enriched.length} leads → enriched_leads.json`); ``` ```php "alice@stripe.com", "domain" => "stripe.com"], ["email" => "bob@notion.so", "domain" => "notion.so"], ["email" => "carol@figma.com", "domain" => "figma.com"], ]; $enriched = []; foreach ($leads as $lead) { $params = http_build_query(["domain" => $lead["domain"]]); $ch = curl_init("https://api.piloterr.com/v2/linkedin/company/info?{$params}"); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_HTTPHEADER, ["x-api-key: {$apiKey}"]); $c = json_decode(curl_exec($ch), true); if (curl_getinfo($ch, CURLINFO_HTTP_CODE) === 200) { $enriched[] = ["email" => $lead["email"], "domain" => $lead["domain"], "company" => $c["company_name"] ?? null, "industry" => $c["industry"] ?? null, "employees" => $c["staff_count"] ?? null, "hq_country" => $c["headquarter"]["country"] ?? null]; } curl_close($ch); usleep(500000); } file_put_contents("enriched_leads.json", json_encode($enriched, JSON_PRETTY_PRINT)); echo "Enriched " . count($enriched) . " leads → enriched_leads.json\n"; ``` ```go package main import ( "encoding/json" "fmt" "io" "net/http" "os" "time" ) func enrichDomain(apiKey, domain string) map[string]any { req, _ := http.NewRequest("GET", "https://api.piloterr.com/v2/linkedin/company/info?domain="+domain, nil) req.Header.Set("x-api-key", apiKey) resp, _ := http.DefaultClient.Do(req) defer resp.Body.Close() body, _ := io.ReadAll(resp.Body) var c map[string]any json.Unmarshal(body, &c) return c } func main() { apiKey := "YOUR_API_KEY" leads := []struct{ Email, Domain string }{ {"alice@stripe.com", "stripe.com"}, {"bob@notion.so", "notion.so"}, {"carol@figma.com", "figma.com"}, } var enriched []map[string]any for _, lead := range leads { c := enrichDomain(apiKey, lead.Domain) hq, _ := c["headquarter"].(map[string]any) enriched = append(enriched, map[string]any{ "email": lead.Email, "domain": lead.Domain, "company": c["company_name"], "industry": c["industry"], "employees": c["staff_count"], "hq_country": hq["country"], }) time.Sleep(500 * time.Millisecond) } b, _ := json.MarshalIndent(enriched, "", " ") os.WriteFile("enriched_leads.json", b, 0644) fmt.Printf("Enriched %d leads → enriched_leads.json\n", len(enriched)) } ``` ```java import java.net.URI; import java.net.http.*; import java.nio.file.*; import java.util.*; import org.json.*; public class Main { public static void main(String[] args) throws Exception { var client = HttpClient.newHttpClient(); var apiKey = "YOUR_API_KEY"; var leads = List.of( Map.of("email", "alice@stripe.com", "domain", "stripe.com"), Map.of("email", "bob@notion.so", "domain", "notion.so"), Map.of("email", "carol@figma.com", "domain", "figma.com")); var enriched = new JSONArray(); for (var lead : leads) { var url = "https://api.piloterr.com/v2/linkedin/company/info?domain=" + lead.get("domain"); var req = HttpRequest.newBuilder().uri(URI.create(url)) .header("x-api-key", apiKey).GET().build(); var resp = client.send(req, HttpResponse.BodyHandlers.ofString()); if (resp.statusCode() == 200) { var c = new JSONObject(resp.body()); var hq = c.optJSONObject("headquarter"); enriched.put(new JSONObject() .put("email", lead.get("email")) .put("domain", lead.get("domain")) .put("company", c.optString("company_name")) .put("industry", c.optString("industry")) .put("employees", c.optInt("staff_count")) .put("hq_country", hq != null ? hq.optString("country") : "")); } Thread.sleep(500); } Files.writeString(Path.of("enriched_leads.json"), enriched.toString(2)); System.out.println("Enriched " + enriched.length() + " leads → enriched_leads.json"); } } ``` ```csharp using System.Net.Http; using System.Text.Json; using var client = new HttpClient(); client.DefaultRequestHeaders.Add("x-api-key", "YOUR_API_KEY"); var leads = new[] { (email: "alice@stripe.com", domain: "stripe.com"), (email: "bob@notion.so", domain: "notion.so"), (email: "carol@figma.com", domain: "figma.com"), }; var enriched = new List(); foreach (var lead in leads) { var resp = await client.GetAsync( $"https://api.piloterr.com/v2/linkedin/company/info?domain={lead.domain}"); if (resp.IsSuccessStatusCode) { var c = JsonDocument.Parse(await resp.Content.ReadAsStringAsync()).RootElement; var hq = c.GetProperty("headquarter"); enriched.Add(new { email = lead.email, domain = lead.domain, company = c.GetProperty("company_name").GetString(), industry = c.GetProperty("industry").GetString(), employees = c.GetProperty("staff_count").GetInt32(), hq_country = hq.GetProperty("country").GetString(), }); } await Task.Delay(500); } File.WriteAllText("enriched_leads.json", JsonSerializer.Serialize(enriched, new JsonSerializerOptions { WriteIndented = true })); Console.WriteLine($"Enriched {enriched.Count} leads → enriched_leads.json"); ``` ```rust use reqwest::Client; use serde_json::{json, Value}; use std::{fs, time::Duration}; use tokio::time::sleep; #[tokio::main] async fn main() -> Result<(), reqwest::Error> { let client = Client::new(); let api_key = "YOUR_API_KEY"; let leads = vec![("alice@stripe.com", "stripe.com"), ("bob@notion.so", "notion.so"), ("carol@figma.com", "figma.com")]; let mut enriched: Vec = Vec::new(); for (email, domain) in &leads { let c = client.get("https://api.piloterr.com/v2/linkedin/company/info") .header("x-api-key", api_key).query(&[("domain", domain)]) .send().await?.json::().await?; enriched.push(json!({ "email": email, "domain": domain, "company": c["company_name"], "industry": c["industry"], "employees": c["staff_count"], "hq_country": c["headquarter"]["country"], })); sleep(Duration::from_millis(500)).await; } fs::write("enriched_leads.json", serde_json::to_string_pretty(&enriched).unwrap()).unwrap(); println!("Enriched {} leads → enriched_leads.json", enriched.len()); Ok(()) } ``` You can also pass a LinkedIn company URL or username to the `query` parameter instead of a domain — useful when you already have the LinkedIn URL from a scrape or manual research. # Crawl Any Website Overview [#overview] This playbook shows how to fetch the full HTML of any webpage using the Piloterr Website Crawler, then extract specific data from it. A typical use case is **competitor price monitoring**: crawl a product page daily and parse the price from the HTML. Prerequisites [#prerequisites] * A Piloterr API key — get one at [app.piloterr.com](https://app.piloterr.com) * Install dependencies for your language: ```bash pip install requests beautifulsoup4 ``` ```bash npm install node-html-parser ``` `curl` and `DOMDocument` extensions (both enabled by default). No extra dependencies for the request — uses `net/http` (Go 1.18+). Add `golang.org/x/net/html` for parsing. No extra dependencies for the request — uses `java.net.http` (Java 11+). Add `org.jsoup:jsoup` for parsing. No extra dependencies for the request — uses `System.Net.Http` (.NET 6+). Add `HtmlAgilityPack` for parsing. ```toml # Cargo.toml [dependencies] reqwest = { version = "0.12", features = ["json"] } tokio = { version = "1", features = ["full"] } serde_json = "1" ``` Steps [#steps] Crawl a webpage [#crawl-a-webpage] Call `GET /v2/website/crawler` with the `query` parameter set to the target URL. The response is the raw HTML string (JSON-encoded). ```python import requests API_KEY = "YOUR_API_KEY" response = requests.get( "https://api.piloterr.com/v2/website/crawler", headers={"x-api-key": API_KEY}, params={"query": "https://example.com", "allow_redirects": "true"}, ) html = response.json() # returns the HTML as a string print(html[:500]) ``` ```typescript const API_KEY = "YOUR_API_KEY"; const params = new URLSearchParams({ query: "https://example.com", allow_redirects: "true" }); const response = await fetch(`https://api.piloterr.com/v2/website/crawler?${params}`, { headers: { "x-api-key": API_KEY }, }); const html: string = await response.json(); console.log(html.slice(0, 500)); ``` ```php "https://example.com", "allow_redirects" => "true"]); $ch = curl_init("https://api.piloterr.com/v2/website/crawler?{$params}"); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_HTTPHEADER, ["x-api-key: {$apiKey}"]); $html = json_decode(curl_exec($ch), true); // HTML string curl_close($ch); echo substr($html, 0, 500); ``` ```go package main import ( "encoding/json" "fmt" "io" "net/http" "net/url" ) func main() { params := url.Values{"query": {"https://example.com"}, "allow_redirects": {"true"}} req, _ := http.NewRequest("GET", "https://api.piloterr.com/v2/website/crawler?"+params.Encode(), nil) req.Header.Set("x-api-key", "YOUR_API_KEY") resp, _ := http.DefaultClient.Do(req) defer resp.Body.Close() body, _ := io.ReadAll(resp.Body) var html string json.Unmarshal(body, &html) // response is a JSON-encoded string fmt.Println(html[:500]) } ``` ```java import java.net.URI; import java.net.http.*; var client = HttpClient.newHttpClient(); var request = HttpRequest.newBuilder() .uri(URI.create("https://api.piloterr.com/v2/website/crawler?query=https%3A%2F%2Fexample.com&allow_redirects=true")) .header("x-api-key", "YOUR_API_KEY") .GET().build(); var response = client.send(request, HttpResponse.BodyHandlers.ofString()); // Response body is a JSON-encoded string — strip the outer quotes var html = response.body().replaceAll("^\"|\"$", "") .replace("\\n", "\n").replace("\\\"", "\""); System.out.println(html.substring(0, Math.min(500, html.length()))); ``` ```csharp using System.Net.Http; using System.Text.Json; using var client = new HttpClient(); client.DefaultRequestHeaders.Add("x-api-key", "YOUR_API_KEY"); var raw = await client.GetStringAsync( "https://api.piloterr.com/v2/website/crawler?query=https%3A%2F%2Fexample.com&allow_redirects=true"); var html = JsonSerializer.Deserialize(raw)!; // response is JSON-encoded string Console.WriteLine(html[..Math.Min(500, html.Length)]); ``` ```rust #[tokio::main] async fn main() -> Result<(), reqwest::Error> { let html = reqwest::Client::new() .get("https://api.piloterr.com/v2/website/crawler") .header("x-api-key", "YOUR_API_KEY") .query(&[("query", "https://example.com"), ("allow_redirects", "true")]) .send().await? .json::().await?; println!("{}", &html[..500.min(html.len())]); Ok(()) } ``` Extract data from the HTML [#extract-data-from-the-html] Parse the HTML to extract specific elements — here we extract the page title and all `

` headings. ```python from bs4 import BeautifulSoup soup = BeautifulSoup(html, "html.parser") title = soup.find("title") print("Page title:", title.text if title else "N/A") for h in soup.find_all("h1"): print("H1:", h.get_text(strip=True)) ``` ```typescript import { parse } from "node-html-parser"; const root = parse(html); const title = root.querySelector("title"); console.log("Page title:", title?.text ?? "N/A"); for (const h of root.querySelectorAll("h1")) { console.log("H1:", h.text.trim()); } ``` ```php $dom = new DOMDocument(); @$dom->loadHTML($html); $xpath = new DOMXPath($dom); $title = $xpath->query("//title")->item(0); echo "Page title: " . ($title ? $title->textContent : "N/A") . "\n"; foreach ($xpath->query("//h1") as $h) { echo "H1: " . trim($h->textContent) . "\n"; } ``` ```go import ( "fmt" "strings" "golang.org/x/net/html" ) doc, _ := html.Parse(strings.NewReader(html)) var traverse func(*html.Node) traverse = func(n *html.Node) { if n.Type == html.ElementNode && n.Data == "title" && n.FirstChild != nil { fmt.Println("Page title:", n.FirstChild.Data) } if n.Type == html.ElementNode && n.Data == "h1" && n.FirstChild != nil { fmt.Println("H1:", n.FirstChild.Data) } for c := n.FirstChild; c != nil; c = c.NextSibling { traverse(c) } } traverse(doc) ``` ```java import org.jsoup.Jsoup; var doc = Jsoup.parse(html); System.out.println("Page title: " + doc.title()); doc.select("h1").forEach(h -> System.out.println("H1: " + h.text())); ``` ```csharp using HtmlAgilityPack; var doc = new HtmlDocument(); doc.LoadHtml(html); var title = doc.DocumentNode.SelectSingleNode("//title"); Console.WriteLine($"Page title: {title?.InnerText ?? "N/A"}"); foreach (var h in doc.DocumentNode.SelectNodes("//h1") ?? Enumerable.Empty()) Console.WriteLine($"H1: {h.InnerText.Trim()}"); ``` ```rust // Minimal regex-based extraction use regex::Regex; // add regex = "1" to Cargo.toml let title_re = Regex::new(r"]*>(.*?)").unwrap(); if let Some(cap) = title_re.captures(&html) { println!("Page title: {}", &cap[1]); } let h1_re = Regex::new(r"]*>(.*?)

").unwrap(); for cap in h1_re.captures_iter(&html) { println!("H1: {}", &cap[1]); } ``` Build a price monitoring script [#build-a-price-monitoring-script] Crawl a product page and extract the price using a CSS selector. ```python import requests from bs4 import BeautifulSoup API_KEY = "YOUR_API_KEY" WATCH_URL = "https://www.example-shop.com/product/123" def crawl(url: str) -> str: r = requests.get("https://api.piloterr.com/v2/website/crawler", headers={"x-api-key": API_KEY}, params={"query": url, "allow_redirects": "true"}) return r.json() def extract_price(html: str) -> str | None: soup = BeautifulSoup(html, "html.parser") el = soup.select_one("[data-price], .price, #price") return el.get_text(strip=True) if el else None price = extract_price(crawl(WATCH_URL)) print(f"Current price: {price}" if price else "Price element not found.") ``` ```typescript import { parse } from "node-html-parser"; const API_KEY = "YOUR_API_KEY"; const WATCH_URL = "https://www.example-shop.com/product/123"; async function crawl(url: string): Promise { const params = new URLSearchParams({ query: url, allow_redirects: "true" }); const res = await fetch(`https://api.piloterr.com/v2/website/crawler?${params}`, { headers: { "x-api-key": API_KEY }, }); return res.json(); } const html = await crawl(WATCH_URL); const root = parse(html); const price = root.querySelector("[data-price], .price, #price")?.text.trim() ?? null; console.log(price ? `Current price: ${price}` : "Price element not found."); ``` ```php $url, "allow_redirects" => "true"]); $ch = curl_init("https://api.piloterr.com/v2/website/crawler?{$params}"); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_HTTPHEADER, ["x-api-key: {$apiKey}"]); $html = json_decode(curl_exec($ch), true); curl_close($ch); return $html; } $html = crawl("YOUR_API_KEY", "https://www.example-shop.com/product/123"); $dom = new DOMDocument(); @$dom->loadHTML($html); $xpath = new DOMXPath($dom); $price = null; foreach (["//span[@class='price']", "//*[@id='price']", "//*[@data-price]"] as $sel) { $nodes = $xpath->query($sel); if ($nodes->length > 0) { $price = trim($nodes->item(0)->textContent); break; } } echo $price ? "Current price: {$price}\n" : "Price element not found.\n"; ``` ```go package main import ( "encoding/json" "fmt" "io" "net/http" "net/url" "regexp" ) func crawl(apiKey, pageUrl string) string { params := url.Values{"query": {pageUrl}, "allow_redirects": {"true"}} req, _ := http.NewRequest("GET", "https://api.piloterr.com/v2/website/crawler?"+params.Encode(), nil) req.Header.Set("x-api-key", apiKey) resp, _ := http.DefaultClient.Do(req) defer resp.Body.Close() body, _ := io.ReadAll(resp.Body) var html string json.Unmarshal(body, &html) return html } func main() { html := crawl("YOUR_API_KEY", "https://www.example-shop.com/product/123") re := regexp.MustCompile(`class="price[^"]*"[^>]*>([^<]+)`) match := re.FindStringSubmatch(html) if match != nil { fmt.Println("Current price:", match[1]) } else { fmt.Println("Price element not found.") } } ``` ```java import java.net.URI; import java.net.URLEncoder; import java.net.http.*; import java.nio.charset.StandardCharsets; import org.jsoup.Jsoup; public class Main { public static void main(String[] args) throws Exception { var apiKey = "YOUR_API_KEY"; var watchUrl = URLEncoder.encode("https://www.example-shop.com/product/123", StandardCharsets.UTF_8); var url = "https://api.piloterr.com/v2/website/crawler?query=" + watchUrl + "&allow_redirects=true"; var client = HttpClient.newHttpClient(); var request = HttpRequest.newBuilder().uri(URI.create(url)) .header("x-api-key", apiKey).GET().build(); var response = client.send(request, HttpResponse.BodyHandlers.ofString()); // Strip JSON string quotes var html = response.body().replaceAll("^\"|\"$", "").replace("\\\"", "\"").replace("\\n", "\n"); var doc = Jsoup.parse(html); var priceEl = doc.selectFirst(".price, #price, [data-price]"); System.out.println(priceEl != null ? "Current price: " + priceEl.text() : "Price element not found."); } } ``` ```csharp using System.Net.Http; using System.Text.Json; using HtmlAgilityPack; using var client = new HttpClient(); client.DefaultRequestHeaders.Add("x-api-key", "YOUR_API_KEY"); var watchUrl = Uri.EscapeDataString("https://www.example-shop.com/product/123"); var raw = await client.GetStringAsync( $"https://api.piloterr.com/v2/website/crawler?query={watchUrl}&allow_redirects=true"); var html = JsonSerializer.Deserialize(raw)!; var doc = new HtmlDocument(); doc.LoadHtml(html); var price = doc.DocumentNode.SelectSingleNode("//*[contains(@class,'price') or @id='price' or @data-price]"); Console.WriteLine(price != null ? $"Current price: {price.InnerText.Trim()}" : "Price element not found."); ``` ```rust use reqwest::Client; use regex::Regex; async fn crawl(client: &Client, api_key: &str, url: &str) -> String { client.get("https://api.piloterr.com/v2/website/crawler") .header("x-api-key", api_key) .query(&[("query", url), ("allow_redirects", "true")]) .send().await.unwrap().json::().await.unwrap() } #[tokio::main] async fn main() -> Result<(), reqwest::Error> { let client = Client::new(); let html = crawl(&client, "YOUR_API_KEY", "https://www.example-shop.com/product/123").await; let re = Regex::new(r#"class="price[^"]*"[^>]*>([^<]+)"#).unwrap(); match re.captures(&html) { Some(cap) => println!("Current price: {}", cap[1].trim()), None => println!("Price element not found."), } Ok(()) } ``` Set `allow_redirects=true` to follow HTTP 301/302 redirects automatically — useful for short URLs or e-commerce platforms that redirect product pages. # Detect Disposable Domains Overview [#overview] Disposable email providers let users create temporary inboxes that get deleted after minutes or days. This playbook shows how to query the Veille domain validation endpoint and use the result to block or flag signups at the point of registration. Prerequisites [#prerequisites] * A Veille API key — get one at [app.veille.io](https://app.veille.io) * Install dependencies for your language: ```bash pip install requests ``` No extra dependencies — uses the native `fetch` API (Node 18+). `curl` extension enabled (on by default). No extra dependencies — uses `net/http` (Go 1.18+). No extra dependencies — uses `java.net.http` (Java 11+). No extra dependencies — uses `System.Net.Http` (.NET 6+). ```toml # Cargo.toml [dependencies] reqwest = { version = "0.12", features = ["json"] } tokio = { version = "1", features = ["full"] } serde_json = "1" ``` Steps [#steps] Check a domain [#check-a-domain] Call `GET /v1/domain` with the `domain` parameter. The response returns whether it is disposable, free, or a custom domain. ```python import requests API_KEY = "YOUR_API_KEY" response = requests.get( "https://api.veille.io/v1/domain", headers={"x-api-key": API_KEY}, params={"domain": "mailinator.com"}, ) result = response.json() print(result) ``` ```typescript const API_KEY = "YOUR_API_KEY"; const params = new URLSearchParams({ domain: "mailinator.com" }); const response = await fetch(`https://api.veille.io/v1/domain?${params}`, { headers: { "x-api-key": API_KEY }, }); const result = await response.json(); console.log(result); ``` ```php "mailinator.com"]); $ch = curl_init("https://api.veille.io/v1/domain?{$params}"); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_HTTPHEADER, ["x-api-key: {$apiKey}"]); $result = json_decode(curl_exec($ch), true); curl_close($ch); print_r($result); ``` ```go package main import ( "encoding/json" "fmt" "io" "net/http" ) func main() { req, _ := http.NewRequest("GET", "https://api.veille.io/v1/domain?domain=mailinator.com", nil) req.Header.Set("x-api-key", "YOUR_API_KEY") resp, _ := http.DefaultClient.Do(req) defer resp.Body.Close() body, _ := io.ReadAll(resp.Body) var result map[string]any json.Unmarshal(body, &result) fmt.Println(result) } ``` ```java import java.net.URI; import java.net.http.*; var client = HttpClient.newHttpClient(); var request = HttpRequest.newBuilder() .uri(URI.create("https://api.veille.io/v1/domain?domain=mailinator.com")) .header("x-api-key", "YOUR_API_KEY") .GET().build(); var response = client.send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.body()); ``` ```csharp using System.Net.Http; using var client = new HttpClient(); client.DefaultRequestHeaders.Add("x-api-key", "YOUR_API_KEY"); var body = await client.GetStringAsync("https://api.veille.io/v1/domain?domain=mailinator.com"); Console.WriteLine(body); ``` ```rust #[tokio::main] async fn main() -> Result<(), reqwest::Error> { let result = reqwest::Client::new() .get("https://api.veille.io/v1/domain") .header("x-api-key", "YOUR_API_KEY") .query(&[("domain", "mailinator.com")]) .send().await?.json::().await?; println!("{:#?}", result); Ok(()) } ``` Read the response fields [#read-the-response-fields] The response includes `is_disposable`, `is_free`, `is_custom`, `domain`, and `provider` (when identified). ```python domain = result.get("domain") is_disposable = result.get("is_disposable") is_free = result.get("is_free") provider = result.get("provider", "unknown") if is_disposable: print(f"❌ {domain} is a DISPOSABLE email provider ({provider}). Block this signup.") elif is_free: print(f"⚠️ {domain} is a free email provider. Consider extra verification.") else: print(f"✅ {domain} looks like a custom / business domain. Allow.") ``` ```typescript const { domain, is_disposable, is_free, provider } = result; if (is_disposable) { console.log(`❌ ${domain} is DISPOSABLE (${provider ?? "unknown"}). Block this signup.`); } else if (is_free) { console.log(`⚠️ ${domain} is a free provider. Consider extra verification.`); } else { console.log(`✅ ${domain} looks like a business domain. Allow.`); } ``` ```php $domain = $result["domain"] ?? ""; $isDisposable = $result["is_disposable"] ?? false; $isFree = $result["is_free"] ?? false; $provider = $result["provider"] ?? "unknown"; if ($isDisposable) { echo "❌ {$domain} is DISPOSABLE ({$provider}). Block this signup.\n"; } elseif ($isFree) { echo "⚠️ {$domain} is free. Consider extra verification.\n"; } else { echo "✅ {$domain} looks like a business domain. Allow.\n"; } ``` ```go domain := result["domain"].(string) isDisposable := result["is_disposable"].(bool) isFree := result["is_free"].(bool) provider, _ := result["provider"].(string) switch { case isDisposable: fmt.Printf("❌ %s is DISPOSABLE (%s). Block this signup.\n", domain, provider) case isFree: fmt.Printf("⚠️ %s is a free provider.\n", domain) default: fmt.Printf("✅ %s is a business domain. Allow.\n", domain) } ``` ```java import org.json.*; var r = new JSONObject(response.body()); var domain = r.getString("domain"); var isDisposable = r.getBoolean("is_disposable"); var isFree = r.getBoolean("is_free"); var provider = r.optString("provider", "unknown"); if (isDisposable) System.out.printf("❌ %s is DISPOSABLE (%s). Block.%n", domain, provider); else if (isFree) System.out.printf("⚠️ %s is free. Extra verification.%n", domain); else System.out.printf("✅ %s is a business domain. Allow.%n", domain); ``` ```csharp using System.Text.Json; var r = JsonDocument.Parse(body).RootElement; var domain = r.GetProperty("domain").GetString(); var isDisposable = r.GetProperty("is_disposable").GetBoolean(); var isFree = r.GetProperty("is_free").GetBoolean(); var provider = r.TryGetProperty("provider", out var p) ? p.GetString() : "unknown"; if (isDisposable) Console.WriteLine($"❌ {domain} is DISPOSABLE ({provider}). Block."); else if (isFree) Console.WriteLine($"⚠️ {domain} is free. Extra verification."); else Console.WriteLine($"✅ {domain} is a business domain. Allow."); ``` ```rust let domain = result["domain"].as_str().unwrap_or(""); let is_disposable = result["is_disposable"].as_bool().unwrap_or(false); let is_free = result["is_free"].as_bool().unwrap_or(false); let provider = result["provider"].as_str().unwrap_or("unknown"); if is_disposable { println!("❌ {} is DISPOSABLE ({}). Block.", domain, provider); } else if is_free { println!("⚠️ {} is free. Extra verification.", domain); } else { println!("✅ {} is a business domain. Allow.", domain); } ``` Integrate into a signup handler [#integrate-into-a-signup-handler] Add the domain check to your registration endpoint and return a validation error before the user record is created. ```python import requests API_KEY = "YOUR_API_KEY" def is_disposable_email(email: str) -> bool: domain = email.split("@")[-1].lower() r = requests.get("https://api.veille.io/v1/domain", headers={"x-api-key": API_KEY}, params={"domain": domain}) return r.json().get("is_disposable", False) def register_user(email: str, password: str) -> dict: if is_disposable_email(email): return {"success": False, "error": "Disposable email addresses are not allowed."} # ... create the user record in your database return {"success": True, "message": f"Welcome, {email}!"} print(register_user("alice@mailinator.com", "secret")) print(register_user("alice@company.com", "secret")) ``` ```typescript const API_KEY = "YOUR_API_KEY"; async function isDisposableEmail(email: string): Promise { const domain = email.split("@").at(-1)!.toLowerCase(); const params = new URLSearchParams({ domain }); const res = await fetch(`https://api.veille.io/v1/domain?${params}`, { headers: { "x-api-key": API_KEY }, }); return (await res.json()).is_disposable ?? false; } async function registerUser(email: string, password: string) { if (await isDisposableEmail(email)) { return { success: false, error: "Disposable email addresses are not allowed." }; } // ... create user record return { success: true, message: `Welcome, ${email}!` }; } console.log(await registerUser("alice@mailinator.com", "secret")); console.log(await registerUser("alice@company.com", "secret")); ``` ```php $domain]); $ch = curl_init("https://api.veille.io/v1/domain?{$params}"); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_HTTPHEADER, ["x-api-key: {$apiKey}"]); $result = json_decode(curl_exec($ch), true); curl_close($ch); return $result["is_disposable"] ?? false; } function registerUser(string $apiKey, string $email, string $password): array { if (isDisposableEmail($apiKey, $email)) { return ["success" => false, "error" => "Disposable email addresses are not allowed."]; } // ... create user record return ["success" => true, "message" => "Welcome, {$email}!"]; } print_r(registerUser("YOUR_API_KEY", "alice@mailinator.com", "secret")); print_r(registerUser("YOUR_API_KEY", "alice@company.com", "secret")); ``` ```go package main import ( "encoding/json" "fmt" "io" "net/http" "strings" ) func isDisposable(apiKey, email string) bool { domain := strings.ToLower(strings.SplitN(email, "@", 2)[1]) req, _ := http.NewRequest("GET", "https://api.veille.io/v1/domain?domain="+domain, nil) req.Header.Set("x-api-key", apiKey) resp, _ := http.DefaultClient.Do(req) defer resp.Body.Close() body, _ := io.ReadAll(resp.Body) var result map[string]any json.Unmarshal(body, &result) v, _ := result["is_disposable"].(bool) return v } func registerUser(apiKey, email, password string) string { if isDisposable(apiKey, email) { return "❌ Disposable email not allowed." } return "✅ Welcome, " + email + "!" } func main() { apiKey := "YOUR_API_KEY" fmt.Println(registerUser(apiKey, "alice@mailinator.com", "secret")) fmt.Println(registerUser(apiKey, "alice@company.com", "secret")) } ``` ```java import java.net.URI; import java.net.http.*; import org.json.*; public class Main { static HttpClient client = HttpClient.newHttpClient(); static String API_KEY = "YOUR_API_KEY"; static boolean isDisposable(String email) throws Exception { var domain = email.substring(email.indexOf('@') + 1).toLowerCase(); var request = HttpRequest.newBuilder() .uri(URI.create("https://api.veille.io/v1/domain?domain=" + domain)) .header("x-api-key", API_KEY).GET().build(); var resp = client.send(request, HttpResponse.BodyHandlers.ofString()); return new JSONObject(resp.body()).optBoolean("is_disposable", false); } static String registerUser(String email, String password) throws Exception { if (isDisposable(email)) return "❌ Disposable email not allowed."; return "✅ Welcome, " + email + "!"; } public static void main(String[] args) throws Exception { System.out.println(registerUser("alice@mailinator.com", "secret")); System.out.println(registerUser("alice@company.com", "secret")); } } ``` ```csharp using System.Net.Http; using System.Text.Json; var apiKey = "YOUR_API_KEY"; using var client = new HttpClient(); client.DefaultRequestHeaders.Add("x-api-key", apiKey); async Task IsDisposable(string email) { var domain = email.Split('@').Last().ToLower(); var body = await client.GetStringAsync($"https://api.veille.io/v1/domain?domain={domain}"); return JsonDocument.Parse(body).RootElement.GetProperty("is_disposable").GetBoolean(); } async Task RegisterUser(string email, string password) => await IsDisposable(email) ? "❌ Disposable email not allowed." : $"✅ Welcome, {email}!"; Console.WriteLine(await RegisterUser("alice@mailinator.com", "secret")); Console.WriteLine(await RegisterUser("alice@company.com", "secret")); ``` ```rust use reqwest::Client; use serde_json::Value; async fn is_disposable(client: &Client, api_key: &str, email: &str) -> bool { let domain = email.split('@').last().unwrap_or("").to_lowercase(); let result = client.get("https://api.veille.io/v1/domain") .header("x-api-key", api_key) .query(&[("domain", domain.as_str())]) .send().await.unwrap().json::().await.unwrap(); result["is_disposable"].as_bool().unwrap_or(false) } #[tokio::main] async fn main() -> Result<(), reqwest::Error> { let client = Client::new(); let api_key = "YOUR_API_KEY"; for email in ["alice@mailinator.com", "alice@company.com"] { if is_disposable(&client, api_key, email).await { println!("❌ {} — disposable. Block.", email); } else { println!("✅ {} — looks valid. Allow.", email); } } Ok(()) } ``` Cache results for frequently checked domains (e.g. in Redis with a 24-hour TTL) to avoid redundant API calls. The list of disposable providers rarely changes within a single day. # Validate Email on Signup Overview [#overview] This playbook shows how to run a full email validation before accepting a signup: syntax check, DNS/MX record lookup, and SMTP reachability. The API returns a `risk_score` (0 = clean, 100 = high risk) that you can use to route users to extra verification steps. Prerequisites [#prerequisites] * A Veille API key — get one at [app.veille.io](https://app.veille.io) * Install dependencies for your language: ```bash pip install requests ``` No extra dependencies — uses the native `fetch` API (Node 18+). `curl` extension enabled (on by default). No extra dependencies — uses `net/http` (Go 1.18+). No extra dependencies — uses `java.net.http` (Java 11+). No extra dependencies — uses `System.Net.Http` (.NET 6+). ```toml # Cargo.toml [dependencies] reqwest = { version = "0.12", features = ["json"] } tokio = { version = "1", features = ["full"] } serde_json = "1" ``` Steps [#steps] Validate an email address [#validate-an-email-address] Call `GET /v1/email` with the `email` parameter. ```python import requests API_KEY = "YOUR_API_KEY" response = requests.get( "https://api.veille.io/v1/email", headers={"x-api-key": API_KEY}, params={"email": "alice@example.com"}, ) result = response.json() print(result) ``` ```typescript const API_KEY = "YOUR_API_KEY"; const params = new URLSearchParams({ email: "alice@example.com" }); const response = await fetch(`https://api.veille.io/v1/email?${params}`, { headers: { "x-api-key": API_KEY }, }); const result = await response.json(); console.log(result); ``` ```php "alice@example.com"]); $ch = curl_init("https://api.veille.io/v1/email?{$params}"); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_HTTPHEADER, ["x-api-key: {$apiKey}"]); $result = json_decode(curl_exec($ch), true); curl_close($ch); print_r($result); ``` ```go package main import ( "encoding/json" "fmt" "io" "net/http" "net/url" ) func main() { params := url.Values{"email": {"alice@example.com"}} req, _ := http.NewRequest("GET", "https://api.veille.io/v1/email?"+params.Encode(), nil) req.Header.Set("x-api-key", "YOUR_API_KEY") resp, _ := http.DefaultClient.Do(req) defer resp.Body.Close() body, _ := io.ReadAll(resp.Body) var result map[string]any json.Unmarshal(body, &result) fmt.Println(result) } ``` ```java import java.net.URI; import java.net.URLEncoder; import java.net.http.*; import java.nio.charset.StandardCharsets; var client = HttpClient.newHttpClient(); var email = URLEncoder.encode("alice@example.com", StandardCharsets.UTF_8); var request = HttpRequest.newBuilder() .uri(URI.create("https://api.veille.io/v1/email?email=" + email)) .header("x-api-key", "YOUR_API_KEY") .GET().build(); var response = client.send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.body()); ``` ```csharp using System.Net.Http; using var client = new HttpClient(); client.DefaultRequestHeaders.Add("x-api-key", "YOUR_API_KEY"); var email = Uri.EscapeDataString("alice@example.com"); var body = await client.GetStringAsync($"https://api.veille.io/v1/email?email={email}"); Console.WriteLine(body); ``` ```rust #[tokio::main] async fn main() -> Result<(), reqwest::Error> { let result = reqwest::Client::new() .get("https://api.veille.io/v1/email") .header("x-api-key", "YOUR_API_KEY") .query(&[("email", "alice@example.com")]) .send().await?.json::().await?; println!("{:#?}", result); Ok(()) } ``` Interpret the result [#interpret-the-result] Key fields: `is_valid`, `is_deliverable`, `is_disposable`, `is_role_account`, `risk_score`, `did_you_mean` (typo suggestion). ```python print(f"Valid : {result['is_valid']}") print(f"Deliverable : {result['is_deliverable']}") print(f"Disposable : {result['is_disposable']}") print(f"Role account: {result['is_role_account']}") print(f"Risk score : {result['risk_score']}/100") if result.get("did_you_mean"): print(f"Did you mean: {result['did_you_mean']}?") ``` ```typescript console.log(`Valid : ${result.is_valid}`); console.log(`Deliverable : ${result.is_deliverable}`); console.log(`Disposable : ${result.is_disposable}`); console.log(`Role account: ${result.is_role_account}`); console.log(`Risk score : ${result.risk_score}/100`); if (result.did_you_mean) console.log(`Did you mean: ${result.did_you_mean}?`); ``` ```php echo "Valid : " . ($result["is_valid"] ? "true" : "false") . "\n"; echo "Deliverable : " . ($result["is_deliverable"] ? "true" : "false") . "\n"; echo "Disposable : " . ($result["is_disposable"] ? "true" : "false") . "\n"; echo "Risk score : {$result['risk_score']}/100\n"; if (!empty($result["did_you_mean"])) echo "Did you mean: {$result['did_you_mean']}?\n"; ``` ```go fmt.Printf("Valid : %v\nDeliverable : %v\nDisposable : %v\nRisk score : %v/100\n", result["is_valid"], result["is_deliverable"], result["is_disposable"], result["risk_score"]) if typo, ok := result["did_you_mean"].(string); ok && typo != "" { fmt.Println("Did you mean:", typo+"?") } ``` ```java import org.json.*; var r = new JSONObject(response.body()); System.out.printf("Valid : %b%nDeliverable : %b%nDisposable : %b%nRisk score : %d/100%n", r.getBoolean("is_valid"), r.getBoolean("is_deliverable"), r.getBoolean("is_disposable"), r.getInt("risk_score")); if (r.has("did_you_mean")) System.out.println("Did you mean: " + r.getString("did_you_mean") + "?"); ``` ```csharp using System.Text.Json; var r = JsonDocument.Parse(body).RootElement; Console.WriteLine($"Valid : {r.GetProperty("is_valid").GetBoolean()}"); Console.WriteLine($"Deliverable : {r.GetProperty("is_deliverable").GetBoolean()}"); Console.WriteLine($"Disposable : {r.GetProperty("is_disposable").GetBoolean()}"); Console.WriteLine($"Risk score : {r.GetProperty("risk_score").GetInt32()}/100"); if (r.TryGetProperty("did_you_mean", out var typo) && typo.GetString() is { } t and not "") Console.WriteLine($"Did you mean: {t}?"); ``` ```rust println!("Valid : {}", result["is_valid"]); println!("Deliverable : {}", result["is_deliverable"]); println!("Disposable : {}", result["is_disposable"]); println!("Risk score : {}/100", result["risk_score"]); if let Some(typo) = result["did_you_mean"].as_str() { if !typo.is_empty() { println!("Did you mean: {}?", typo); } } ``` Build a risk-tiered registration flow [#build-a-risk-tiered-registration-flow] Use `risk_score` to route users: block high-risk addresses, prompt typo corrections, and apply extra friction to role accounts. ```python import requests API_KEY = "YOUR_API_KEY" def validate_email(email: str) -> dict: r = requests.get("https://api.veille.io/v1/email", headers={"x-api-key": API_KEY}, params={"email": email}) return r.json() def register(email: str) -> dict: v = validate_email(email) if not v.get("is_valid"): return {"ok": False, "error": "This email address is invalid."} if v.get("is_disposable"): return {"ok": False, "error": "Temporary email addresses are not accepted."} if v.get("did_you_mean"): return {"ok": False, "suggestion": f"Did you mean {v['did_you_mean']}?"} if v.get("risk_score", 0) >= 70: return {"ok": False, "error": "This email has a high risk score. Please use a different address."} if v.get("is_role_account"): # Allow but flag for manual review return {"ok": True, "flag": "role_account", "message": "Please verify your email."} return {"ok": True, "message": "Registration successful!"} for test_email in ["alice@mailinator.com", "info@company.com", "alice@gmial.com", "alice@stripe.com"]: print(f"{test_email}: {register(test_email)}") ``` ```typescript const API_KEY = "YOUR_API_KEY"; async function validateEmail(email: string) { const params = new URLSearchParams({ email }); const res = await fetch(`https://api.veille.io/v1/email?${params}`, { headers: { "x-api-key": API_KEY }, }); return res.json(); } async function register(email: string) { const v = await validateEmail(email); if (!v.is_valid) return { ok: false, error: "Invalid email address." }; if (v.is_disposable) return { ok: false, error: "Temporary emails not accepted." }; if (v.did_you_mean) return { ok: false, suggestion: `Did you mean ${v.did_you_mean}?` }; if (v.risk_score >= 70) return { ok: false, error: "High risk score — please use another address." }; if (v.is_role_account) return { ok: true, flag: "role_account", message: "Please verify your email." }; return { ok: true, message: "Registration successful!" }; } for (const email of ["alice@mailinator.com", "info@company.com", "alice@gmial.com", "alice@stripe.com"]) { console.log(email, await register(email)); } ``` ```php $email]); $ch = curl_init("https://api.veille.io/v1/email?{$params}"); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_HTTPHEADER, ["x-api-key: {$apiKey}"]); $result = json_decode(curl_exec($ch), true); curl_close($ch); return $result; } function register(string $apiKey, string $email): array { $v = validateEmail($apiKey, $email); if (!($v["is_valid"] ?? false)) return ["ok" => false, "error" => "Invalid email."]; if ($v["is_disposable"] ?? false) return ["ok" => false, "error" => "Temporary emails not accepted."]; if (!empty($v["did_you_mean"])) return ["ok" => false, "suggestion" => "Did you mean {$v['did_you_mean']}?"]; if (($v["risk_score"] ?? 0) >= 70) return ["ok" => false, "error" => "High risk score."]; if ($v["is_role_account"] ?? false) return ["ok" => true, "flag" => "role_account"]; return ["ok" => true, "message" => "Registration successful!"]; } foreach (["alice@mailinator.com", "info@company.com", "alice@gmial.com"] as $email) { print_r(["email" => $email, "result" => register("YOUR_API_KEY", $email)]); } ``` ```go package main import ( "encoding/json" "fmt" "io" "net/http" "net/url" ) const APIKey = "YOUR_API_KEY" func validate(email string) map[string]any { params := url.Values{"email": {email}} req, _ := http.NewRequest("GET", "https://api.veille.io/v1/email?"+params.Encode(), nil) req.Header.Set("x-api-key", APIKey) resp, _ := http.DefaultClient.Do(req) defer resp.Body.Close() body, _ := io.ReadAll(resp.Body) var v map[string]any json.Unmarshal(body, &v) return v } func register(email string) string { v := validate(email) if !(v["is_valid"].(bool)) { return "❌ Invalid email." } if v["is_disposable"].(bool) { return "❌ Disposable not accepted." } if typo, ok := v["did_you_mean"].(string); ok && typo != "" { return "⚠️ Did you mean " + typo + "?" } if v["risk_score"].(float64) >= 70 { return "❌ High risk score." } return "✅ Registration successful!" } func main() { for _, email := range []string{"alice@mailinator.com", "info@company.com", "alice@stripe.com"} { fmt.Printf("%s: %s\n", email, register(email)) } } ``` ```java import java.net.URI; import java.net.URLEncoder; import java.net.http.*; import java.nio.charset.StandardCharsets; import org.json.*; public class Main { static HttpClient client = HttpClient.newHttpClient(); static String API_KEY = "YOUR_API_KEY"; static JSONObject validate(String email) throws Exception { var encoded = URLEncoder.encode(email, StandardCharsets.UTF_8); var req = HttpRequest.newBuilder() .uri(URI.create("https://api.veille.io/v1/email?email=" + encoded)) .header("x-api-key", API_KEY).GET().build(); var resp = client.send(req, HttpResponse.BodyHandlers.ofString()); return new JSONObject(resp.body()); } static String register(String email) throws Exception { var v = validate(email); if (!v.getBoolean("is_valid")) return "❌ Invalid email."; if (v.getBoolean("is_disposable")) return "❌ Disposable not accepted."; if (v.has("did_you_mean")) return "⚠️ Did you mean " + v.getString("did_you_mean") + "?"; if (v.getInt("risk_score") >= 70) return "❌ High risk score."; return "✅ Registration successful!"; } public static void main(String[] args) throws Exception { for (var email : new String[]{"alice@mailinator.com", "info@company.com", "alice@stripe.com"}) { System.out.printf("%s: %s%n", email, register(email)); } } } ``` ```csharp using System.Net.Http; using System.Text.Json; var apiKey = "YOUR_API_KEY"; using var client = new HttpClient(); client.DefaultRequestHeaders.Add("x-api-key", apiKey); async Task Validate(string email) { var encoded = Uri.EscapeDataString(email); var body = await client.GetStringAsync($"https://api.veille.io/v1/email?email={encoded}"); return JsonDocument.Parse(body).RootElement; } async Task Register(string email) { var v = await Validate(email); if (!v.GetProperty("is_valid").GetBoolean()) return "❌ Invalid email."; if (v.GetProperty("is_disposable").GetBoolean()) return "❌ Disposable not accepted."; if (v.TryGetProperty("did_you_mean", out var t) && t.GetString() is { Length: > 0 } typo) return $"⚠️ Did you mean {typo}?"; if (v.GetProperty("risk_score").GetInt32() >= 70) return "❌ High risk score."; return "✅ Registration successful!"; } foreach (var email in new[] { "alice@mailinator.com", "info@company.com", "alice@stripe.com" }) Console.WriteLine($"{email}: {await Register(email)}"); ``` ```rust use reqwest::Client; use serde_json::Value; const API_KEY: &str = "YOUR_API_KEY"; async fn validate(client: &Client, email: &str) -> Value { client.get("https://api.veille.io/v1/email") .header("x-api-key", API_KEY) .query(&[("email", email)]) .send().await.unwrap().json::().await.unwrap() } async fn register(client: &Client, email: &str) -> &'static str { let v = validate(client, email).await; if !v["is_valid"].as_bool().unwrap_or(false) { return "❌ Invalid email."; } if v["is_disposable"].as_bool().unwrap_or(false) { return "❌ Disposable not accepted."; } if v["risk_score"].as_i64().unwrap_or(0) >= 70 { return "❌ High risk score."; } "✅ Registration successful!" } #[tokio::main] async fn main() -> Result<(), reqwest::Error> { let client = Client::new(); for email in ["alice@mailinator.com", "info@company.com", "alice@stripe.com"] { println!("{}: {}", email, register(&client, email).await); } Ok(()) } ``` Role accounts (`admin@`, `info@`, `support@`) are often monitored by multiple people — or not monitored at all. Flag them for manual review rather than blocking outright to avoid losing legitimate B2B signups. # Validate EU VAT Numbers Overview [#overview] EU businesses are exempt from VAT when purchasing from other EU businesses — but only with a valid VAT number. This playbook shows how to validate a VAT number at checkout and retrieve the associated company details (name and address) from the VIES database. Prerequisites [#prerequisites] * A Veille API key — get one at [app.veille.io](https://app.veille.io) * Install dependencies for your language: ```bash pip install requests ``` No extra dependencies — uses the native `fetch` API (Node 18+). `curl` extension enabled (on by default). No extra dependencies — uses `net/http` (Go 1.18+). No extra dependencies — uses `java.net.http` (Java 11+). No extra dependencies — uses `System.Net.Http` (.NET 6+). ```toml # Cargo.toml [dependencies] reqwest = { version = "0.12", features = ["json"] } tokio = { version = "1", features = ["full"] } serde_json = "1" ``` Steps [#steps] Validate a VAT number [#validate-a-vat-number] Call `GET /v1/vat` with the `vat` parameter. The number should include the country prefix (e.g. `FR12345678901`). ```python import requests API_KEY = "YOUR_API_KEY" response = requests.get( "https://api.veille.io/v1/vat", headers={"x-api-key": API_KEY}, params={"vat": "FR12345678901"}, ) result = response.json() print(result) ``` ```typescript const API_KEY = "YOUR_API_KEY"; const params = new URLSearchParams({ vat: "FR12345678901" }); const response = await fetch(`https://api.veille.io/v1/vat?${params}`, { headers: { "x-api-key": API_KEY }, }); const result = await response.json(); console.log(result); ``` ```php "FR12345678901"]); $ch = curl_init("https://api.veille.io/v1/vat?{$params}"); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_HTTPHEADER, ["x-api-key: {$apiKey}"]); $result = json_decode(curl_exec($ch), true); curl_close($ch); print_r($result); ``` ```go package main import ( "encoding/json" "fmt" "io" "net/http" ) func main() { req, _ := http.NewRequest("GET", "https://api.veille.io/v1/vat?vat=FR12345678901", nil) req.Header.Set("x-api-key", "YOUR_API_KEY") resp, _ := http.DefaultClient.Do(req) defer resp.Body.Close() body, _ := io.ReadAll(resp.Body) var result map[string]any json.Unmarshal(body, &result) fmt.Println(result) } ``` ```java import java.net.URI; import java.net.http.*; var client = HttpClient.newHttpClient(); var request = HttpRequest.newBuilder() .uri(URI.create("https://api.veille.io/v1/vat?vat=FR12345678901")) .header("x-api-key", "YOUR_API_KEY") .GET().build(); var response = client.send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.body()); ``` ```csharp using System.Net.Http; using var client = new HttpClient(); client.DefaultRequestHeaders.Add("x-api-key", "YOUR_API_KEY"); var body = await client.GetStringAsync("https://api.veille.io/v1/vat?vat=FR12345678901"); Console.WriteLine(body); ``` ```rust #[tokio::main] async fn main() -> Result<(), reqwest::Error> { let result = reqwest::Client::new() .get("https://api.veille.io/v1/vat") .header("x-api-key", "YOUR_API_KEY") .query(&[("vat", "FR12345678901")]) .send().await?.json::().await?; println!("{:#?}", result); Ok(()) } ``` Read the company details [#read-the-company-details] A valid number returns `is_valid: true`, the `company_name`, `company_address`, and `country_code`. ```python if result.get("is_valid"): print(f"✅ Valid VAT number") print(f" Company : {result.get('company_name')}") print(f" Address : {result.get('company_address')}") print(f" Country : {result.get('country_code')}") else: print(f"❌ Invalid VAT number: {result.get('error', 'Not found in VIES')}") ``` ```typescript if (result.is_valid) { console.log("✅ Valid VAT number"); console.log(` Company : ${result.company_name}`); console.log(` Address : ${result.company_address}`); console.log(` Country : ${result.country_code}`); } else { console.log(`❌ Invalid VAT number: ${result.error ?? "Not found in VIES"}`); } ``` ```php if ($result["is_valid"] ?? false) { echo "✅ Valid VAT number\n"; echo " Company : {$result['company_name']}\n"; echo " Address : {$result['company_address']}\n"; echo " Country : {$result['country_code']}\n"; } else { echo "❌ Invalid VAT number: " . ($result["error"] ?? "Not found in VIES") . "\n"; } ``` ```go if result["is_valid"].(bool) { fmt.Printf("✅ Valid VAT number\n Company : %v\n Address : %v\n Country : %v\n", result["company_name"], result["company_address"], result["country_code"]) } else { errMsg := "Not found in VIES" if e, ok := result["error"].(string); ok { errMsg = e } fmt.Println("❌ Invalid VAT number:", errMsg) } ``` ```java import org.json.*; var r = new JSONObject(response.body()); if (r.getBoolean("is_valid")) { System.out.printf("✅ Valid VAT number%n Company : %s%n Address : %s%n Country : %s%n", r.getString("company_name"), r.getString("company_address"), r.getString("country_code")); } else { System.out.println("❌ Invalid VAT number: " + r.optString("error", "Not found in VIES")); } ``` ```csharp using System.Text.Json; var r = JsonDocument.Parse(body).RootElement; if (r.GetProperty("is_valid").GetBoolean()) { Console.WriteLine("✅ Valid VAT number"); Console.WriteLine($" Company : {r.GetProperty("company_name")}"); Console.WriteLine($" Address : {r.GetProperty("company_address")}"); Console.WriteLine($" Country : {r.GetProperty("country_code")}"); } else { var error = r.TryGetProperty("error", out var e) ? e.GetString() : "Not found in VIES"; Console.WriteLine($"❌ Invalid VAT number: {error}"); } ``` ```rust if result["is_valid"].as_bool().unwrap_or(false) { println!("✅ Valid VAT number"); println!(" Company : {}", result["company_name"].as_str().unwrap_or("")); println!(" Address : {}", result["company_address"].as_str().unwrap_or("")); println!(" Country : {}", result["country_code"].as_str().unwrap_or("")); } else { let err = result["error"].as_str().unwrap_or("Not found in VIES"); println!("❌ Invalid VAT number: {}", err); } ``` Build a B2B checkout VAT handler [#build-a-b2b-checkout-vat-handler] Strip VAT from the order total when a verified EU business VAT number is provided. ```python import requests API_KEY = "YOUR_API_KEY" VAT_RATE = 0.20 # 20% VAT def lookup_vat(number: str) -> dict: r = requests.get("https://api.veille.io/v1/vat", headers={"x-api-key": API_KEY}, params={"vat": number}) return r.json() def calculate_checkout(subtotal: float, vat_number: str | None = None) -> dict: vat_amount = subtotal * VAT_RATE vat_info = None if vat_number: result = lookup_vat(vat_number) if result.get("is_valid"): vat_amount = 0 # B2B reverse charge — no VAT charged vat_info = {"company": result["company_name"], "country": result["country_code"]} else: return {"error": "The VAT number you provided is not valid."} total = subtotal + vat_amount return {"subtotal": subtotal, "vat": vat_amount, "total": total, "company": vat_info} print(calculate_checkout(100.00)) print(calculate_checkout(100.00, vat_number="FR12345678901")) print(calculate_checkout(100.00, vat_number="INVALID123")) ``` ```typescript const API_KEY = "YOUR_API_KEY"; const VAT_RATE = 0.20; async function lookupVat(number: string) { const params = new URLSearchParams({ vat: number }); const res = await fetch(`https://api.veille.io/v1/vat?${params}`, { headers: { "x-api-key": API_KEY }, }); return res.json(); } async function calculateCheckout(subtotal: number, vatNumber?: string) { let vatAmount = subtotal * VAT_RATE; let companyInfo: any = null; if (vatNumber) { const result = await lookupVat(vatNumber); if (result.is_valid) { vatAmount = 0; companyInfo = { company: result.company_name, country: result.country_code }; } else { return { error: "The VAT number you provided is not valid." }; } } return { subtotal, vat: vatAmount, total: subtotal + vatAmount, company: companyInfo }; } console.log(await calculateCheckout(100)); console.log(await calculateCheckout(100, "FR12345678901")); console.log(await calculateCheckout(100, "INVALID123")); ``` ```php $number]); $ch = curl_init("https://api.veille.io/v1/vat?{$params}"); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_HTTPHEADER, ["x-api-key: {$apiKey}"]); $result = json_decode(curl_exec($ch), true); curl_close($ch); return $result; } function calculateCheckout(string $apiKey, float $subtotal, ?string $vatNumber = null): array { $vatAmount = $subtotal * VAT_RATE; $company = null; if ($vatNumber) { $result = lookupVat($apiKey, $vatNumber); if ($result["is_valid"] ?? false) { $vatAmount = 0; $company = ["company" => $result["company_name"], "country" => $result["country_code"]]; } else { return ["error" => "Invalid VAT number."]; } } return ["subtotal" => $subtotal, "vat" => $vatAmount, "total" => $subtotal + $vatAmount, "company" => $company]; } print_r(calculateCheckout("YOUR_API_KEY", 100.0)); print_r(calculateCheckout("YOUR_API_KEY", 100.0, "FR12345678901")); ``` ```go package main import ( "encoding/json" "fmt" "io" "net/http" ) const APIKey = "YOUR_API_KEY" const VATRate = 0.20 func lookupVAT(number string) map[string]any { req, _ := http.NewRequest("GET", "https://api.veille.io/v1/vat?vat="+number, nil) req.Header.Set("x-api-key", APIKey) resp, _ := http.DefaultClient.Do(req) defer resp.Body.Close() body, _ := io.ReadAll(resp.Body) var r map[string]any json.Unmarshal(body, &r) return r } func calculateCheckout(subtotal float64, vatNumber string) map[string]any { vatAmount := subtotal * VATRate var company map[string]any if vatNumber != "" { result := lookupVAT(vatNumber) if result["is_valid"].(bool) { vatAmount = 0 company = map[string]any{"company": result["company_name"], "country": result["country_code"]} } else { return map[string]any{"error": "Invalid VAT number."} } } return map[string]any{"subtotal": subtotal, "vat": vatAmount, "total": subtotal + vatAmount, "company": company} } func main() { fmt.Println(calculateCheckout(100, "")) fmt.Println(calculateCheckout(100, "FR12345678901")) fmt.Println(calculateCheckout(100, "INVALID123")) } ``` ```java import java.net.URI; import java.net.http.*; import org.json.*; public class Main { static HttpClient client = HttpClient.newHttpClient(); static String API_KEY = "YOUR_API_KEY"; static double VAT_RATE = 0.20; static JSONObject lookupVat(String number) throws Exception { var req = HttpRequest.newBuilder() .uri(URI.create("https://api.veille.io/v1/vat?vat=" + number)) .header("x-api-key", API_KEY).GET().build(); var resp = client.send(req, HttpResponse.BodyHandlers.ofString()); return new JSONObject(resp.body()); } static JSONObject calculateCheckout(double subtotal, String vatNumber) throws Exception { double vatAmount = subtotal * VAT_RATE; JSONObject company = null; if (vatNumber != null && !vatNumber.isEmpty()) { var result = lookupVat(vatNumber); if (result.getBoolean("is_valid")) { vatAmount = 0; company = new JSONObject().put("company", result.getString("company_name")) .put("country", result.getString("country_code")); } else { return new JSONObject().put("error", "Invalid VAT number."); } } return new JSONObject().put("subtotal", subtotal).put("vat", vatAmount) .put("total", subtotal + vatAmount).put("company", company); } public static void main(String[] args) throws Exception { System.out.println(calculateCheckout(100, null)); System.out.println(calculateCheckout(100, "FR12345678901")); System.out.println(calculateCheckout(100, "INVALID123")); } } ``` ```csharp using System.Net.Http; using System.Text.Json; const double VAT_RATE = 0.20; var apiKey = "YOUR_API_KEY"; using var client = new HttpClient(); client.DefaultRequestHeaders.Add("x-api-key", apiKey); async Task LookupVat(string number) { var body = await client.GetStringAsync($"https://api.veille.io/v1/vat?vat={number}"); return JsonDocument.Parse(body).RootElement; } async Task CalculateCheckout(double subtotal, string? vatNumber = null) { double vatAmount = subtotal * VAT_RATE; string? company = null; if (vatNumber != null) { var result = await LookupVat(vatNumber); if (result.GetProperty("is_valid").GetBoolean()) { vatAmount = 0; company = result.GetProperty("company_name").GetString(); } else return """{"error":"Invalid VAT number."}"""; } return $"""{{ "subtotal": {subtotal}, "vat": {vatAmount}, "total": {subtotal + vatAmount}, "company": "{company}" }}"""; } Console.WriteLine(await CalculateCheckout(100)); Console.WriteLine(await CalculateCheckout(100, "FR12345678901")); Console.WriteLine(await CalculateCheckout(100, "INVALID123")); ``` ```rust use reqwest::Client; use serde_json::{json, Value}; const VAT_RATE: f64 = 0.20; const API_KEY: &str = "YOUR_API_KEY"; async fn lookup_vat(client: &Client, number: &str) -> Value { client.get("https://api.veille.io/v1/vat") .header("x-api-key", API_KEY) .query(&[("vat", number)]) .send().await.unwrap().json::().await.unwrap() } async fn calculate_checkout(client: &Client, subtotal: f64, vat_number: Option<&str>) -> Value { let mut vat_amount = subtotal * VAT_RATE; let mut company = json!(null); if let Some(number) = vat_number { let result = lookup_vat(client, number).await; if result["is_valid"].as_bool().unwrap_or(false) { vat_amount = 0.0; company = json!({"company": result["company_name"], "country": result["country_code"]}); } else { return json!({ "error": "Invalid VAT number." }); } } json!({ "subtotal": subtotal, "vat": vat_amount, "total": subtotal + vat_amount, "company": company }) } #[tokio::main] async fn main() -> Result<(), reqwest::Error> { let client = Client::new(); println!("{}", calculate_checkout(&client, 100.0, None).await); println!("{}", calculate_checkout(&client, 100.0, Some("FR12345678901")).await); println!("{}", calculate_checkout(&client, 100.0, Some("INVALID123")).await); Ok(()) } ``` Always store the validated company name and address alongside the order record. EU tax authorities require proof that the reverse-charge mechanism was correctly applied.