Openmart AI - Search businesses API docs

Parameter	Type	Required	Example	Description
`query`	string	Yes	"hair salons"	The type of business you want to find.
`location`	array	No	[{"country":"USA","state":"CA","city":"San Francisco"}]	The location to search in.
`has_website`	boolean	No	true	Only return businesses that have a website.
`has_valid_website`	boolean	No	true	Only return businesses with a valid website.
`has_contact_info`	boolean	No	true	Only return businesses that have contact information.

Response element	Description
Top-level array	The response itself is the list of matching businesses when estimate_total is false.
`id`	The Openmart business ID. You can also copy it into tracking_id when enriching contacts.
`content.root_domain`	The company domain to send as domain in a find_people request.
`content.business_name`	The company name to send as company_name when enriching contacts.
`cursor`	Copy the final result cursor into the next search request.

Parameter	Type	Required	Example	Description
`query`	string	Yes	"restaurants"	The type of business you want to find.
`location`	array	No	[{"country":"USA","state":"CA"}]	The location to search in.
`min_locations`	integer	No	3	Only return businesses with at least this many locations.

Response element	Description
Top-level array	The response itself is the list of matching businesses when estimate_total is false.
`id`	The Openmart business ID. You can also copy it into tracking_id when enriching contacts.
`content.root_domain`	The company domain to send as domain in a find_people request.
`content.business_name`	The company name to send as company_name when enriching contacts.
`cursor`	Copy the final result cursor into the next search request.

Request body for POST /api/v1/search and POST /api/v1/search/only_ids. All fields are optional. Order below follows typical usage: query and limit first, then geography and filters, then pagination and the rest.

Most common parameters

Start here for most integrations. These are the fields teams adjust first when building lists and running day-to-day searches.

querystringRequired: No

Example: "hair salons"

Primary free-text search (1–500 characters). Configure this first unless you use tags instead. Ignored for matching when tags is non-empty.

cURL example

cURL

curl --request POST \
  --url https://api.openmart.ai/api/v1/search \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_api_key>' \
  --header 'Content-Type: application/json' \
  --data '{"query":"hair salons"}'

limitintegerRequired: No

Example: 100

Page size: number of records to return per request (1–1000). Recommended: 100 for typical integrations. Preview API keys must be 100 or less.

cURL example

cURL

curl --request POST \
  --url https://api.openmart.ai/api/v1/search \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_api_key>' \
  --header 'Content-Type: application/json' \
  --data '{"query":"restaurants","limit":100}'

locationarray[object]Required: No

Example: [{"country":"USA","state":"CA","city":"San Francisco"}]

Geographic filters. Pass a single Location object or an array of them.

cURL example

cURL

curl --request POST \
  --url https://api.openmart.ai/api/v1/search \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_api_key>' \
  --header 'Content-Type: application/json' \
  --data '{"query":"hair salons","location":[{"country":"USA","state":"CA","city":"San Francisco"}]}'

has_websitebooleanRequired: No

Example: true

If true, only businesses that have any website URL.

cURL example

cURL

curl --request POST \
  --url https://api.openmart.ai/api/v1/search \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_api_key>' \
  --header 'Content-Type: application/json' \
  --data '{"query":"hair salons","has_website":true}'

has_valid_websitebooleanRequired: No

Example: true

If true, only businesses with a validated website URL.

cURL example

cURL

curl --request POST \
  --url https://api.openmart.ai/api/v1/search \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_api_key>' \
  --header 'Content-Type: application/json' \
  --data '{"query":"hair salons","has_valid_website":true}'

has_contact_infobooleanRequired: No

Example: true

If true, only businesses that have contact-related signals in the index.

cURL example

cURL

curl --request POST \
  --url https://api.openmart.ai/api/v1/search \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_api_key>' \
  --header 'Content-Type: application/json' \
  --data '{"query":"hair salons","has_contact_info":true}'

tagsarray[string]Required: No

Example: ["restaurants","pizza"]

Search by tag labels (up to 100). If this array is non-empty, tag-based matching is used and query is ignored.

cURL example

cURL

curl --request POST \
  --url https://api.openmart.ai/api/v1/search \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_api_key>' \
  --header 'Content-Type: application/json' \
  --data '{"tags":["restaurants","pizza"],"limit":50}'

store_namestringRequired: No

Example: "Blue Bottle Coffee"

Filter or boost by store or listing name in addition to query when applicable.

cURL example

cURL

curl --request POST \
  --url https://api.openmart.ai/api/v1/search \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_api_key>' \
  --header 'Content-Type: application/json' \
  --data '{"query":"coffee","store_name":"Blue Bottle Coffee"}'

min_locationsintegerRequired: No

Example: 3

Minimum number of locations or stores for the brand.

cURL example

cURL

curl --request POST \
  --url https://api.openmart.ai/api/v1/search \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_api_key>' \
  --header 'Content-Type: application/json' \
  --data '{"query":"restaurants","min_locations":3}'

Location object fields

Use these inside the `location` array when you want to narrow a search by city, ZIP code, or radius.

countrystringRequired: No

Example: "USA"

Country code or name. Defaults to US when omitted.

cURL example

cURL

curl --request POST \
  --url https://api.openmart.ai/api/v1/search \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_api_key>' \
  --header 'Content-Type: application/json' \
  --data '{"query":"restaurants","location":[{"country":"USA"}]}'

statestringRequired: No

Example: "CA"

State or region name.

cURL example

cURL

curl --request POST \
  --url https://api.openmart.ai/api/v1/search \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_api_key>' \
  --header 'Content-Type: application/json' \
  --data '{"query":"restaurants","location":[{"country":"USA","state":"CA"}]}'

citystringRequired: No

Example: "San Francisco"

City name filter.

cURL example

cURL

curl --request POST \
  --url https://api.openmart.ai/api/v1/search \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_api_key>' \
  --header 'Content-Type: application/json' \
  --data '{"query":"hair salons","location":[{"country":"USA","state":"CA","city":"San Francisco"}]}'

zip_codearray[string]Required: No

Example: ["94107","94110"]

One or more postal or ZIP codes. A single string is also accepted and coerced server-side.

cURL example

cURL

curl --request POST \
  --url https://api.openmart.ai/api/v1/search \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_api_key>' \
  --header 'Content-Type: application/json' \
  --data '{"query":"restaurants","location":[{"zip_code":["94107","94110"]}]}'

latnumberRequired: No

Example: 37.7749

Latitude (WGS84), paired with long for radius search.

cURL example

cURL

curl --request POST \
  --url https://api.openmart.ai/api/v1/search \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_api_key>' \
  --header 'Content-Type: application/json' \
  --data '{"query":"restaurants","location":[{"lat":37.7749,"long":-122.4194,"geo_radius":5000}]}'

longnumberRequired: No

Example: -122.4194

Longitude (WGS84), paired with lat for radius search.

cURL example

cURL

curl --request POST \
  --url https://api.openmart.ai/api/v1/search \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_api_key>' \
  --header 'Content-Type: application/json' \
  --data '{"query":"restaurants","location":[{"lat":37.7749,"long":-122.4194,"geo_radius":5000}]}'

geo_radiusintegerRequired: No

Example: 5000

Radius in meters around lat/long. Used only when both coordinates are set.

cURL example

cURL

curl --request POST \
  --url https://api.openmart.ai/api/v1/search \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_api_key>' \
  --header 'Content-Type: application/json' \
  --data '{"query":"restaurants","location":[{"lat":37.7749,"long":-122.4194,"geo_radius":5000}]}'

use_geo_fuzzbooleanRequired: No

Example: true

If true, prefer radius/geo behavior over city/state/zip. If false, city/zip filters apply without geo fuzz.

cURL example

cURL

curl --request POST \
  --url https://api.openmart.ai/api/v1/search \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_api_key>' \
  --header 'Content-Type: application/json' \
  --data '{"query":"restaurants","location":[{"lat":37.7749,"long":-122.4194,"geo_radius":5000,"use_geo_fuzz":true}]}'

normalize_fieldsarray[string]Required: No

Example: ["city","state"]

Optional fields to normalize in geocoding (advanced).

cURL example

cURL

curl --request POST \
  --url https://api.openmart.ai/api/v1/search \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_api_key>' \
  --header 'Content-Type: application/json' \
  --data '{"query":"restaurants","location":[{"country":"USA","normalize_fields":["city","state"]}]}'

Business quality and scale filters

These filters are useful when you want better-fit businesses by rating, review volume, price point, ownership type, or location count.

min_overall_ratingnumberRequired: No

Example: 4.2

Minimum Google-style overall rating (0–5).

cURL example

cURL

curl --request POST \
  --url https://api.openmart.ai/api/v1/search \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_api_key>' \
  --header 'Content-Type: application/json' \
  --data '{"query":"coffee shops","min_overall_rating":4.2}'

max_overall_ratingnumberRequired: No

Example: 4.8

Maximum Google-style overall rating (0–5).

cURL example

cURL

curl --request POST \
  --url https://api.openmart.ai/api/v1/search \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_api_key>' \
  --header 'Content-Type: application/json' \
  --data '{"query":"coffee shops","max_overall_rating":4.8}'

min_total_reviewsintegerRequired: No

Example: 100

Minimum total review count.

cURL example

cURL

curl --request POST \
  --url https://api.openmart.ai/api/v1/search \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_api_key>' \
  --header 'Content-Type: application/json' \
  --data '{"query":"restaurants","min_total_reviews":100}'

max_total_reviewsintegerRequired: No

Example: 500

Maximum total review count.

cURL example

cURL

curl --request POST \
  --url https://api.openmart.ai/api/v1/search \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_api_key>' \
  --header 'Content-Type: application/json' \
  --data '{"query":"restaurants","max_total_reviews":500}'

min_price_tierintegerRequired: No

Example: 2

Minimum price tier filter (provider-specific scale).

cURL example

cURL

curl --request POST \
  --url https://api.openmart.ai/api/v1/search \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_api_key>' \
  --header 'Content-Type: application/json' \
  --data '{"query":"restaurants","min_price_tier":2}'

max_price_tierintegerRequired: No

Example: 4

Maximum price tier filter (provider-specific scale).

cURL example

cURL

curl --request POST \
  --url https://api.openmart.ai/api/v1/search \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_api_key>' \
  --header 'Content-Type: application/json' \
  --data '{"query":"restaurants","max_price_tier":4}'

max_locationsintegerRequired: No

Example: 20

Maximum number of locations or stores for the brand, paired with min_locations.

cURL example

cURL

curl --request POST \
  --url https://api.openmart.ai/api/v1/search \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_api_key>' \
  --header 'Content-Type: application/json' \
  --data '{"query":"restaurants","max_locations":20}'

ownership_typestringRequired: No

Example: "franchise"

Filter by ownership classification when indexed. Exact meaning depends on the data pipeline.

cURL example

cURL

curl --request POST \
  --url https://api.openmart.ai/api/v1/search \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_api_key>' \
  --header 'Content-Type: application/json' \
  --data '{"query":"restaurants","ownership_type":"franchise"}'

Pagination and response shape

Use these when you need to page through large result sets or estimate the size of a result set before processing it.

cursorarrayRequired: No

Example: [0.93,"f7f7f5b7-1111-2222-3333-123456789abc"]

Opaque pagination token: a two-element array [match_score, store_id]. Omit it for the first page and reuse the last result cursor for the next page.

cURL example

cURL

curl --request POST \
  --url https://api.openmart.ai/api/v1/search \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_api_key>' \
  --header 'Content-Type: application/json' \
  --data '{"query":"restaurants","limit":100,"cursor":[0.93,"f7f7f5b7-1111-2222-3333-123456789abc"]}'

estimate_totalbooleanRequired: No

Example: true

If true, the response is wrapped as {data, total_count} and includes an estimated hit count.

cURL example

cURL

curl --request POST \
  --url https://api.openmart.ai/api/v1/search \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_api_key>' \
  --header 'Content-Type: application/json' \
  --data '{"query":"restaurants","estimate_total":true}'

Keyword and domain filters

These are stronger content filters for inclusion, exclusion, and domain cleanup when your workflow needs tighter control.

include_keywordsarray[string]Required: No

Example: ["organic","vegan"]

Businesses whose text should mention these terms (up to 64 strings).

cURL example

cURL

curl --request POST \
  --url https://api.openmart.ai/api/v1/search \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_api_key>' \
  --header 'Content-Type: application/json' \
  --data '{"query":"restaurants","include_keywords":["organic","vegan"]}'

exclude_keywordsarray[string]Required: No

Example: ["hotel","resort"]

Businesses whose text must not mention these terms (up to 64 strings).

cURL example

cURL

curl --request POST \
  --url https://api.openmart.ai/api/v1/search \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_api_key>' \
  --header 'Content-Type: application/json' \
  --data '{"query":"restaurants","exclude_keywords":["hotel","resort"]}'

exclude_root_domainsarray[string]Required: No

Example: ["yelp.com","facebook.com"]

Exclude businesses whose website root domain matches any of these.

cURL example

cURL

curl --request POST \
  --url https://api.openmart.ai/api/v1/search \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_api_key>' \
  --header 'Content-Type: application/json' \
  --data '{"query":"restaurants","exclude_root_domains":["yelp.com","facebook.com"]}'

Time-based filters

open_date_afterstringRequired: No

Example: "2026-03-01T00:00:00Z"

Only businesses opened on or after this ISO 8601 instant. This is the API equivalent of the self-serve “New businesses” filter. Set it to the opening-date cutoff; optionally pair it with open_date_before for a fixed window.

cURL example

cURL

curl --request POST \
  --url https://api.openmart.ai/api/v1/search \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_api_key>' \
  --header 'Content-Type: application/json' \
  --data '{"query":"restaurants","open_date_after":"2026-03-01T00:00:00Z","open_date_before":"2026-06-01T00:00:00Z"}'

open_date_beforestringRequired: No

Example: "2026-06-01T00:00:00Z"

Only businesses opened on or before this ISO 8601 instant. Pair it with open_date_after when you want the self-serve “New businesses” filter as a fixed opening-date window.

cURL example

cURL

curl --request POST \
  --url https://api.openmart.ai/api/v1/search \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_api_key>' \
  --header 'Content-Type: application/json' \
  --data '{"query":"restaurants","open_date_after":"2026-03-01T00:00:00Z","open_date_before":"2026-06-01T00:00:00Z"}'

info_updated_afterstringRequired: No

Example: "2025-01-01T00:00:00Z"

Lower bound on last info refresh time. Accepts ISO datetime strings and some millisecond timestamps.

cURL example

cURL

curl --request POST \
  --url https://api.openmart.ai/api/v1/search \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_api_key>' \
  --header 'Content-Type: application/json' \
  --data '{"query":"restaurants","info_updated_after":"2025-01-01T00:00:00Z"}'

info_updated_beforestringRequired: No

Example: "2025-12-31T23:59:59Z"

Upper bound on last info refresh time, with the same accepted formats as info_updated_after.

cURL example

cURL

curl --request POST \
  --url https://api.openmart.ai/api/v1/search \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_api_key>' \
  --header 'Content-Type: application/json' \
  --data '{"query":"restaurants","info_updated_before":"2025-12-31T23:59:59Z"}'

Search businesses

Overview

Before you start

Example 1: Search hair salons in San Francisco, CA

Parameters

cURL request

Response details

Response example

Key elements of the API response

Example 2: Search restaurants in California with at least 3 locations

Parameters

cURL request

Response details

Response example

Key elements of the API response

Next: find owner contacts

All request parameters

Most common parameters

Location object fields

Business quality and scale filters

Pagination and response shape

Keyword and domain filters

Time-based filters

If this request fails