REST API quickstart
Use your own application or terminal with the same searches, results and credits.
curl https://api.mapbulk.com/v1/usage \
-H "Authorization: Bearer YOUR_API_KEY"
# MapBulk CLI (Python 3.11)
python -m pip install "./mapbulk_mvp-0.1.0-py3-none-any.whl[cli]"
mapbulk --version
mapbulk usage
mapbulk categories --query restaurant --limit 20Create a key
On Scale or Max, open API, MCP & CLI in your dashboard. Create a key for the required access and keep the secret in your backend environment.
Check your connection
GET /v1/usage returns your balances and usage after applying scheduled paid-credit expiry. Use your Authorization: Bearer header. This does not start a search or buy credits. The endpoint is https://api.mapbulk.com.
Install the CLI
Use Python 3.11. Download the MapBulk 0.1.0 wheel. Open a terminal in the folder containing the downloaded wheel, then run the install and connection commands above. The executable is mapbulk; the Python distribution is mapbulk-mvp. Authenticated commands prompt for your key without displaying it. For scripts, inject MAPBULK_API_KEY from your secret manager; never pass a key as a command-line argument. Scale and Max include this access.
Choose business categories
Use mapbulk categories --query restaurant --limit 20, GET /v1/categories?query=restaurant&limit=20 or the MCP list_business_categories tool. Keep the returned catalog version and selectable node IDs in category_selection. A parent includes its descendants; browse nodes are navigation only. Category mode excludes keywords. Use Custom keywords for a literal search; do not replace an unavailable pinned version.
Set the target and budget
Two integer units equal one displayed credit. A finite search needs result_cap and maximum_credit_units. result_mode:emails targets businesses with an accepted email; with enrichment on, only those are delivered, at two units each. All available requires result_mode:all with both values null and binds the initial available wallet. In the CLI, this also requires --spend-entire-wallet --yes. Target and budget remain independent. Read the REST schemas for the exact request fields, including name, query, country_code and non-empty locations.
Work with searches
Create a search, keep its ID, read its status, then request paginated results. Use mapbulk searches create with --input search.json and --idempotency-key, then searches show, results or issues with the returned ID. Results, leads and issues contain at most 20 records per page; search history uses searches list and accepts up to 100. Pass each returned cursor unchanged with the same filters. Every write needs an idempotency key and explicit inputs; preserve both after a lost response. The CLI makes no automatic retries or polling.
Enrich or control an existing list
Use searches enrich for existing websites, searches cancel to stop a list, or searches retry for an eligible failed operation. Enrichment uses the stored campaign credit ceiling. For your own website data, use imports create, batch and complete with prepared JSON request files before requesting enrichment. CSV column mapping remains in the dashboard.
Retrieve exports
Pass has_email:true to request email-only results and the same export selection. only_with_email enables enrichment and the dashboard view; API, MCP and CLI reads do not inherit that view. In the CLI add --has-email true to searches results or leads and to exports create. Exports wait for collection to finish. CSV, JSON and XLSX share the same versioned fields. The category field describes the observed Google Maps business category, not the chosen search category. Existing files retain their original schema. Use exports status before exports download with --output and a fresh filename. Download links expire; files can be regenerated.