Maps Search

Search Maps for local businesses and save the places into a Parvenu list.

POST /maps_search_list

Maps Search costs 1 credit per place returned. With find_contact on, each contact costs 1 credit when its email is valid or catch-all and nothing when it is not.

Search Maps the way a customer would, by a term like plumbers plus a place, and write every business found into a list. Each place is saved with its name, website, category, full address, phone number, rating, review count and map URL.

Credits are reserved when the search is submitted and the unused part is refunded when it finishes. Asking for 1,000 places holds 1,000 credits and returns the balance if only 800 come back. Contacts are charged after they are found and are not part of the reservation.

This is a bulk endpoint. The process has three steps: (1) start the search here, (2) check status with /check_list_status, (3) download results with /download_list.

Headers

Name	Value
Content-Type	application/json

Body

Name	Type	Description
api_key	string	Your API Key.
listname	string	The list to create or add the places to.
search_term	string	What to search for, e.g. "plumbers".
max_results	integer	Optional. Places to fetch. Minimum 1, default 10.
country	string	Optional. Country to search in, e.g. "United States".
state	string	Optional. State or province to search in.
city	string	Optional. City to search in.
postal_code	string	Optional. Postal or ZIP code to narrow the search.
require_website	boolean	Optional. Drop places that have no website (default false). Dropped places are not billed.
find_contact	boolean	Optional. Also look for people working at each place found (default false). Needs at least one job title in titles. 1 credit per contact with a valid or catch-all email, nothing for the rest, on top of the per-place charge.
titles	array[string]	Required when find_contact is true: at least one job title, e.g. ["Owner","President","General Manager"]. Without one the request is refused and nothing is charged.
contact_location	array[string]	Optional. Location filter for those contacts. Look values up with /search_lead_locations.

Give as much of country, state, city and postal_code as you have. The narrower the area, the closer the results are to what you would see searching the map yourself.

Most local businesses have no website, and a place with a phone number is still a lead, so they are kept by default. Set require_website to true if you only want ones with a site.

For local businesses, ask for owner-level titles such as owner, president or general manager. Small businesses rarely list HR or recruiting roles.

Response

This endpoint starts a background job and answers with an acknowledgement, not the places. See Response Format for the fields every endpoint returns.

Field	Description
status	Job state: queued, processing, done, not_found, cancelled or error.
job_id	The job handle, as a string.
list_name	The list the places are being written to.
rows_selected	How many places the job will actually look for.
max_rows	How many you asked for.
truncated	true when the job was cut down to fit your balance.
credits_estimated	Credits reserved for the run. The unused part is refunded when it finishes.
credits_per_row	Credits charged per place returned.
contacts_max	With find_contact on, the most contacts this run can return. 0 otherwise.
contacts_credits_max	The most the contacts can cost: 1 credit each, charged only for contacts with a valid or catch-all email.
message	A short note about the job.

Poll /check_list_status until the list reports done, then download the rows.

Example

Input

{
  "api_key": "your_api_key",
  "listname": "Boulder Dentists",
  "search_term": "dental clinics",
  "city": "Boulder",
  "state": "Colorado",
  "country": "United States",
  "max_results": 3,
  "require_website": false
}

Output

{
  "status": "queued",
  "job_id": "1042",
  "list_name": "Boulder Dentists",
  "rows_selected": 3,
  "max_rows": 3,
  "truncated": false,
  "credits_estimated": 3,
  "credits_per_row": 1,
  "contacts_max": 0,
  "contacts_credits_max": 0,
  "message": "Maps search queued for 3 places. 3 credits reserved; unused credits are refunded when the run finishes.",
  "view": "all",
  "credits_remaining": 4820,
  "success": true
}

Error

{
  "status": "error",
  "error": {
    "code": "validation_error",
    "message": "search_term: Field required"
  },
  "success": false
}

Error: no job title

Returned with HTTP 422 when find_contact is true and titles is empty. Nothing is charged.

{
  "status": "error",
  "error": {
    "code": "http_error",
    "message": "Add at least one job title to find contacts (for example: owner, president, general manager). Turn off \"find contacts\" to search for businesses only."
  },
  "success": false
}

What each place comes back with

Field	Description
organization_name	The business name.
current_company_website	Its website, when it has one.
current_industry	The listing category, e.g. Dentist.
address	Street address.
city	City.
state	State or province.
postal_code	Postal or ZIP code.
country	Country name.
country_code	Two-letter country code.
company_phone	Phone number on the listing.
rating	Star rating out of 5.
review_count	How many reviews that rating is based on.
google_maps_url	Link to the listing on the map.
place_id	The map provider's ID for the place.

To sanity-check a search term before a large run, send it with max_results: 5 into a scratch list. Five credits, and the rows come back the same way.

Retrieving results

• Check List Status

• Download List Data