{ "openapi": "3.0.1", "info": { "title": "Bulk Address Verification API - US, Canada and Worldwide", "description": "Verify, correct and standardize postal addresses in the US, Canada and worldwide. Freeform or structured input, batches of up to 2000 addresses per call, ZIP+4, county, delivery point validation and geocodes, plus address suggestions, address parsing and postal code lookups. Bring your own API key.", "version": "0.1", "x-build-id": "cu6zztYqZMJRC43i0" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/nabeelbaghoor~bulk-address-verification-api/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-nabeelbaghoor-bulk-address-verification-api", "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/nabeelbaghoor~bulk-address-verification-api/runs": { "post": { "operationId": "runs-sync-nabeelbaghoor-bulk-address-verification-api", "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/nabeelbaghoor~bulk-address-verification-api/run-sync": { "post": { "operationId": "run-sync-nabeelbaghoor-bulk-address-verification-api", "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": { "mode": { "title": "What this run does", "enum": [ "verify", "verifyInternational", "suggest", "parse", "cityState", "zipCodes" ], "type": "string", "description": "Verification cleans and standardizes addresses, and comes in two coverage areas because the provider runs two services: one for the US and Canada with USPS and Canada Post detail, one for the rest of the world. The other modes answer smaller questions: suggestions offer candidates for an address that did not verify, parsing breaks a line into components, and the two postal code modes go between a code and the places it covers.", "default": "verify" }, "apiKey": { "title": "API key", "type": "string", "description": "Your own account's API key for this provider, created in its dashboard under Developers. Bring your own key: nothing is shared between runs and the key is never written to the dataset. A test key only answers test data, so use a live key for real addresses." }, "addresses": { "title": "Addresses", "type": "array", "description": "One entry per line. In the verification and suggestion modes a line is a whole address written on one line, and adding the two letter country code at the end improves the match. In parse mode it is the address to break apart. In city and state lookup mode it is a ZIP or postal code. In ZIP code lookup mode it is a US city and state, for example New York, NY.", "items": { "type": "string" } }, "structuredAddresses": { "title": "Structured addresses", "type": "array", "description": "Addresses you already hold as separate columns, one object per address, used by the two verification modes and by suggestions. Fields are the provider's own: line1, line2, city, provinceOrState, postalOrZip, country, firmName, recipient and id. Common spreadsheet names such as street, state, zip, postcode, company and name are accepted and rewritten. Only line1 is required." }, "defaultCountry": { "title": "Default country", "type": "string", "description": "Country applied to a structured address that does not carry one, as a two letter ISO code. Leave it empty to send those addresses without a country and let the provider infer it.", "default": "US" }, "includeDetails": { "title": "Include address details", "type": "boolean", "description": "Ask for the full detail block on each verified address: street number, name, type and direction, suite, county and FIPS code, carrier route, delivery point validation, residential and vacancy flags, time zone and area code. Turning it off returns only the standardized address.", "default": true }, "geoData": { "title": "Include coordinates (worldwide mode)", "type": "boolean", "description": "Ask the worldwide service for latitude, longitude and a geocode accuracy level on each address. Only applies to worldwide verification, because the US and Canada service returns its geocode without being asked.", "default": false }, "skipUnverified": { "title": "Only keep verified addresses", "type": "boolean", "description": "Leave addresses that did not verify out of the dataset. They are still counted and still billed by the provider, because the lookup happened either way, so this is about the shape of your output rather than the cost of the run.", "default": false }, "batchSize": { "title": "Addresses per request", "minimum": 1, "maximum": 2000, "type": "integer", "description": "How many addresses go into one batch call, up to the provider's ceiling of 2000. Larger batches are faster and cheaper in requests, but a batch bigger than the lookups left on your account fails as a whole, so lower this when an allowance is nearly spent.", "default": 500 }, "maxResults": { "title": "Maximum rows", "minimum": 1, "maximum": 100000, "type": "integer", "description": "Stop after this many rows. Some modes return several rows for one entry, for example a suggestion list or every ZIP code in a city, so this is a cap on output rather than on input.", "default": 100 }, "requestsPerMinute": { "title": "Requests per minute", "minimum": 1, "maximum": 240, "type": "integer", "description": "How fast this actor calls the provider. The documented limit is five requests a second, so this is capped at 240 a minute, which leaves headroom on an account that is also serving your own application.", "default": 120 } } }, "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 } } } } } } } } } }