{ "openapi": "3.0.1", "info": { "title": "GoodFirms Agency Directory Scraper — Rating, Rate & Employees", "description": "Search the GoodFirms B2B agency directory by category. Returns each listed agency's rating, review count, hourly rate, employee range, location, founding year, website, and (best-effort) email/phone/full address/services.", "version": "0.1", "x-build-id": "Vlz50njwKcRkAZm5j" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/bovi~goodfirms-agency-directory/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-bovi-goodfirms-agency-directory", "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/bovi~goodfirms-agency-directory/runs": { "post": { "operationId": "runs-sync-bovi-goodfirms-agency-directory", "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/bovi~goodfirms-agency-directory/run-sync": { "post": { "operationId": "run-sync-bovi-goodfirms-agency-directory", "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", "required": [ "categories" ], "properties": { "categories": { "title": "Category slugs", "type": "array", "description": "GoodFirms category URL slugs to scrape, exactly as they appear at goodfirms.co/ (e.g. 'seo-agencies', 'ecommerce-development-companies', 'cloud-computing-companies', 'devops-companies', 'advertising-companies'). This is NOT a free-text keyword search — the slug must be a real GoodFirms category URL segment, not a guessed one (e.g. 'web-design-companies' does not exist even though it reads naturally). Browse goodfirms.co and copy the last path segment of a category page's URL to find a valid slug. Each category is scraped independently.", "items": { "type": "string" } }, "maxItems": { "title": "Max items per category", "minimum": 1, "maximum": 2000, "type": "integer", "description": "Maximum number of agency records to return per category.", "default": 20 }, "maxPages": { "title": "Max listing pages per category", "minimum": 1, "maximum": 100, "type": "integer", "description": "How many category-listing pages (~48 agencies/page) to fetch per category before stopping.", "default": 3 }, "fetchDetails": { "title": "Fetch full company profile (email, phone, full address, services)", "type": "boolean", "description": "If true (recommended), visits each company's own GoodFirms profile page for bonus fields: email, phone, full street address, and services offered. The core fields (name, website, rating, review count, hourly rate, employees, location) are already complete from the category listing alone, so turning this off only drops the bonus fields, never a whole record — but the run is faster with it off.", "default": true }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "Proxy settings. Use Apify Proxy with the RESIDENTIAL group for reliable access to GoodFirms." } } }, "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 } } } } } } } } } }