{ "openapi": "3.0.1", "info": { "title": "Aviso Legal Scraper — Spain CIF, Registro Mercantil & Contacts", "description": "Turn Spanish company domains into verified B2B/KYB leads from each site's statutory Aviso Legal (Ley 34/2002): legal name, CIF/NIF with the official AEAT check digit, Registro Mercantil province + tomo/folio/hoja, domicilio social, email and phone.", "version": "0.1", "x-build-id": "HJjEhIISbDbxJRNPS" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/scrapersdelight~aviso-legal-contact-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-scrapersdelight-aviso-legal-contact-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/scrapersdelight~aviso-legal-contact-scraper/runs": { "post": { "operationId": "runs-sync-scrapersdelight-aviso-legal-contact-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/scrapersdelight~aviso-legal-contact-scraper/run-sync": { "post": { "operationId": "run-sync-scrapersdelight-aviso-legal-contact-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "domains": { "title": "Company domains", "type": "array", "description": "One entry per Spanish company. Paste bare domains (\"suavinex.com\"), full homepage URLs (\"https://www.joyeriasuarez.com\") or a direct Aviso Legal URL. Everything is normalised to the registrable domain (eTLD+1), so one domain = one row = one charge.", "items": { "type": "string" } }, "startUrls": { "title": "Start URLs", "type": "array", "description": "The same input in Apify's Start-URLs shape, so the Console link-list UX and \"link list from a file\" uploads work. Merged with Company domains.", "default": [], "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "sourceDatasetId": { "title": "Source dataset ID", "type": "string", "description": "Chain straight off another Actor's dataset — e.g. a Google Maps Spain or Páginas Amarillas run — instead of pasting a list. Every item's website field becomes an input domain.", "default": "" }, "sourceDatasetField": { "title": "Source dataset field", "type": "string", "description": "Which field of the source dataset holds the website. Falls back automatically through website, url, domain, web, site, homepage, link, companyWebsite.", "default": "website" }, "domainsFileUrl": { "title": "Domain list URL (.txt / .csv)", "type": "string", "description": "Public URL of a newline-delimited .txt or a .csv/.tsv of domains, for very large lists. A CSV header naming the source field (or website/url/domain) picks the column; otherwise the most domain-looking column is used.", "default": "" }, "excludeDomains": { "title": "Exclude domains (suppression list)", "type": "array", "description": "Already-contacted or unwanted domains. Applied BEFORE any request is made, so an excluded domain never costs a fetch and can never be billed.", "default": [], "items": { "type": "string" } }, "maxItems": { "title": "Max domains", "minimum": 0, "type": "integer", "description": "Hard cap on domains processed this run — your billing guard. Default 1000. Set 0 to process the whole input list.", "default": 1000 }, "requestConcurrency": { "title": "Request concurrency", "minimum": 1, "maximum": 20, "type": "integer", "description": "Domains fetched in parallel. Measured stable at 6-8; ECONNRESETs start appearing as this climbs toward 20.", "default": 8 }, "maxRequestsPerDomain": { "title": "Max requests per domain", "minimum": 1, "maximum": 40, "type": "integer", "description": "Caps the discovery ladder (homepage + footer candidates + URL guesses). Measured average is 5.5 requests per domain.", "default": 12 }, "requestTimeoutSecs": { "title": "Request timeout (seconds)", "minimum": 5, "maximum": 120, "type": "integer", "description": "Per-request timeout.", "default": 20 }, "maxRetriesPerRequest": { "title": "Max retries per request", "minimum": 1, "maximum": 8, "type": "integer", "description": "Attempts per URL, each on a FRESH proxy IP. Measured: 2 of 30 sustained-load calls only succeeded on attempt 2 or later, and the HTTP client's own retry reuses the flagged IP — so this loop is what buys the 96.8% success rate.", "default": 3 }, "proxyConfiguration": { "title": "Proxy", "type": "object", "description": "Apify DATACENTER proxy is the default and is MEASURED sufficient — it returned byte-identical pages to a direct connection across the 50-domain corpus. Residential is available as an override but does not fix the enterprise-WAF failures.", "default": { "useApifyProxy": true } }, "proxyCountry": { "title": "Proxy country", "enum": [ "none", "ES", "PT", "FR", "DE", "GB", "US" ], "type": "string", "description": "Country pin. Applies ONLY when the proxy above uses the RESIDENTIAL group (datacenter pools ignore a country pin).", "default": "none" }, "escalateToResidentialOnBlock": { "title": "Escalate to residential on a block", "type": "boolean", "description": "Retry a 403/429 on RESIDENTIAL-ES. Default OFF because it was MEASURED not to fix the enterprise-WAF class (pccomponentes.com is 403 on both datacenter and residential-ES) — it costs residential traffic for nothing on that class.", "default": false }, "renderJavaScript": { "title": "Render JavaScript (Chromium fallback)", "type": "boolean", "description": "Opt-in headless-Chromium pass for sites whose footer is client-side rendered, where the Aviso Legal link exists nowhere in the raw HTML (mango.com, eroski.es, misako.com). REQUIRES the run memory to be set to 2048 MB — below 1536 MB the Actor logs a warning and stays on HTTP rather than risk an out-of-memory kill. Rendered rows bill the separate, higher aviso-legal-rendered event.", "default": false }, "userAgent": { "title": "User-Agent override", "type": "string", "description": "Advanced: replace the default desktop Chrome User-Agent.", "default": "" }, "customHeaders": { "title": "Custom headers", "type": "object", "description": "Advanced: extra request headers merged over the defaults (Accept-Language is es-ES,es;q=0.9,en;q=0.7).", "default": {} }, "respectRobotsTxt": { "title": "Respect robots.txt", "type": "boolean", "description": "Read each site's robots.txt and skip URLs its wildcard user-agent group disallows. Off by default; the Aviso Legal page is a statutory public disclosure under Ley 34/2002 art. 10 and is normally crawlable.", "default": false }, "avisoLegalPaths": { "title": "URL-guess ladder", "type": "array", "description": "Tried when the homepage exposes no Aviso Legal link. Measured: 4 of 50 domains resolve here (/aviso-legal x3, /aviso-legal/ x1). Extend or replace freely.", "default": [ "/aviso-legal", "/aviso-legal/", "/es/aviso-legal", "/pages/aviso-legal", "/aviso-legal.html", "/legal", "/avisolegal", "/aviso_legal", "/nota-legal", "/informacion-legal" ], "items": { "type": "string" } }, "extendedPaths": { "title": "Extended path ladder (opt-in)", "type": "array", "description": "A second, slower tier tried only when the first ladder finds nothing. Measured win: forumsport.com's full LSSI block (CIF A48450456, Registro Mercantil de Bizkaia, Tomo 95) lives on /condiciones-generales, not on any /aviso-legal path. Empty by default because it costs extra requests per unresolved domain.", "default": [], "items": { "type": "string" } }, "scoreAllCandidates": { "title": "Score every candidate page", "type": "boolean", "description": "Evaluate EVERY discovered Aviso Legal candidate and keep the highest-scoring one (valid CIF +3, Registro Mercantil +2, domicilio social +1, locale preference as a tiebreak) instead of accepting the first page that loads. Keep this ON: first-hit-wins is what made tous.com resolve to /us-es/ and return a New York address and a US EIN instead of the Spanish entity.", "default": true }, "preferredLocales": { "title": "Preferred locales", "type": "array", "description": "Ordered locale preference used to SCORE candidate URLs, and to add locale variants as extra candidates. Never used to rewrite a URL outright — hard-forcing /es-es/ 404s on joyeriasuarez.com. The empty entry means \"a path with no locale segment\".", "default": [ "es-es", "es", "ca", "eu", "gl", "" ], "items": { "type": "string" } }, "contactPageFallback": { "title": "Fall back to /contacto", "type": "boolean", "description": "If no Aviso Legal page resolves, try the contact page for an email and phone only. The row is marked status=partial and is delivered FREE — it is never charged.", "default": false }, "validateTaxId": { "title": "Validate the CIF / NIF / NIE", "type": "boolean", "description": "Run the official AEAT check-digit algorithm on every extracted tax id and emit taxIdValid + taxIdType. Zero external calls. Measured: 25 of 25 tax ids extracted across the probe corpus PASSED.", "default": true }, "verifyMx": { "title": "Verify the email domain accepts mail (MX)", "type": "boolean", "description": "DNS MX lookup on the extracted email's domain; emits emailMxValid. Adds a DNS round-trip per unique domain.", "default": false }, "includePersonalNames": { "title": "Include personal names (administrador)", "type": "boolean", "description": "Extract the administrador / representante legal person name. Personal data under the GDPR — OFF by default; enabling it makes you the controller for that field.", "default": false }, "includePersonalEmails": { "title": "Include personal emails", "type": "boolean", "description": "Include name.surname@ style addresses. OFF by default — only role addresses (info@, legal@, lopd@, contacto@ …) are returned.", "default": false }, "minFieldsRequired": { "title": "Minimum fields for a billable lead", "minimum": 0, "maximum": 4, "type": "integer", "description": "How many of {taxId, legalName, email, phone} a page must yield before the row counts as a resolved lead (status=ok) and is therefore charged. Anything below the bar is delivered as status=partial, free.", "default": 2 }, "legalFormFilter": { "title": "Filter by legal form (CIF first letter)", "type": "array", "description": "Keep only companies whose CIF starts with one of these letters — the CIF-keyed prospecting lever. A = S.A., B = S.L., F = cooperativa, G = asociación/fundación, J = sociedad civil, N = entidad extranjera, U = UTE, W = establecimiento permanente. Empty = keep everything.", "default": [], "items": { "type": "string" } }, "provinceFilter": { "title": "Filter by province", "type": "array", "description": "Keep only rows whose Registro Mercantil province — or, failing that, the province derived from the postal code — is in this list. Accepts Spanish, Catalan, Basque and Galician names (Vizcaya = Bizkaia, Gerona = Girona). Empty = keep everything.", "default": [], "items": { "type": "string" } }, "postalCodeFilter": { "title": "Filter by postal-code prefix", "type": "array", "description": "Explicit CP prefixes, e.g. [\"28\", \"08\"] for Madrid and Barcelona, or [\"280\"] for a tighter cut. Empty = keep everything.", "default": [], "items": { "type": "string" } }, "onlyResolved": { "title": "Only push resolved leads", "type": "boolean", "description": "Drop blocked / not-found / partial rows entirely. OFF by default so you can see exactly what happened to every domain you submitted — those rows are always free.", "default": false }, "dedupeByDomain": { "title": "Deduplicate by domain", "type": "boolean", "description": "Collapse subdomains onto their registrable domain (eTLD+1) before fetching. Exact duplicate hostnames are ALWAYS collapsed regardless of this switch — that is the double-charge guard.", "default": true }, "dedupeByTaxId": { "title": "Deduplicate by tax ID", "type": "boolean", "description": "Collapse several brand domains that share one validated CIF into a single row. Off by default because you usually want a row per domain you submitted.", "default": false }, "includeRawText": { "title": "Include the raw Aviso Legal text", "type": "boolean", "description": "Attach the page's plain text (rawText) for audit or LLM post-processing. Off by default — it multiplies dataset size.", "default": false }, "outputMode": { "title": "Output mode", "enum": [ "lead", "full" ], "type": "string", "description": "\"Lead\" is one flat row per domain. \"Full\" adds emails[], phones[], allUrlsTried, the candidate score and the render flag.", "default": "lead" } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } }