Database Search Planner API

Describe who you want in plain English ("dentists in Austin", "websites that use Shopify", "CEOs of SaaS companies in Texas") or what you sell ("I sell life insurance"), and get ready-to-run searches for the Lead, Local Business and E-commerce databases: filters set to values the database really has, how many records match (leaving out what your account already has), and the exact parameters to send to that database API. GET with query parameters or POST with a JSON body. Requires $149/mo plan.

Included with $149/mo planGET /api/v1/database/plan

Database APIs are included with the $149/mo plan.

Parameters

Name	Type	Required	Description
`query`	string	Required	What you are looking for, or what you sell, in plain English. Name as many places as you want ("dentists in Austin, San Antonio and Dallas"), or put a list of places one per line (up to 5,000); send long lists with POSTExample: dentists in Austin
`database`	string	Optional	Plan for one database only: leads (people at companies), local (local businesses) or ecommerce (online stores). Leave it out and the planner picks the databases that fit.Example: local

Examples

Plan a Local Business Database search

curl "https://app.scrapercity.com/api/v1/database/plan?query=dentists%20in%20Austin&database=local" \
  -H "Authorization: Bearer YOUR_API_KEY"

Let the planner pick the databases, then run the first search it returns

curl -X POST "https://app.scrapercity.com/api/v1/database/plan" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "I sell email marketing to Shopify stores"}'
# Each search in the response has apiEndpoint (e.g. database/ecommerce) and apiParams:
# send apiParams as they are to https://app.scrapercity.com/api/v1/<apiEndpoint>

Use Cases

•Turn a plain-English request from your own tool or agent into exact database filters
•Find the right database and filters for an offer before pulling leads
•Check how many new records a search would return before running it

Best Practices

•A request for something specific ("dentists in Austin") returns one search with just those filters
•A description of what you sell returns up to 3 searches for your best customers in each database that fits
•Send apiParams exactly as returned: every value is one the database has
•Planning does not count toward the 100,000 records a day limit
•Rate limit: 20 plans per minute

Every scrape returns a runId. Poll GET /api/v1/scrape/status/{runId} until it completes, then download via GET /api/downloads/{runId}?format=csv.

Authenticate every request with Authorization: Bearer YOUR_API_KEY. See the full API reference for authentication, rate limits and error codes.

Database Search Planner API API Documentation