> For the complete documentation index, see [llms.txt](https://developer.parvenu.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.parvenu.io/search/maps-search.md). # Maps Search Search Maps for local businesses and save the places into a Parvenu list. `POST` `/maps_search_list` {% hint style="info" %} 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. {% endhint %} 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. {% hint style="info" %} 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`. {% endhint %} **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`. | {% hint style="info" %} 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. {% endhint %} {% hint style="info" %} 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. {% endhint %} {% hint style="info" %} For local businesses, ask for owner-level titles such as owner, president or general manager. Small businesses rarely list HR or recruiting roles. {% endhint %} **Response** This endpoint starts a background job and answers with an acknowledgement, not the places. See [Response Format](/getting-started/response-format.md) 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** {% tabs %} {% tab title="Input" %} ```json { "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 } ``` {% endtab %} {% tab title="Output" %} ```json { "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 } ``` {% endtab %} {% tab title="Error" %} ```json { "status": "error", "error": { "code": "validation_error", "message": "search_term: Field required" }, "success": false } ``` {% endtab %} {% tab title="Error: no job title" %} Returned with HTTP 422 when `find_contact` is true and `titles` is empty. Nothing is charged. ```json { "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 } ``` {% endtab %} {% endtabs %} **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. | {% hint style="success" %} 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. {% endhint %} **Retrieving results** * [Check List Status](/get-enrichment-results/check-list-status.md) * [Download List Data](/get-enrichment-results/download-list-data.md)