The unique ID for a business. Use it to fetch more details later.
Response element
Business fields
Description
May include fields such as name, website, location, and number of locations.
Response element
Description
results
The list of matching businesses.
Business record
One matching business in the results list.
openmart_id
The unique ID for a business. Use it to fetch more details later.
Business fields
May include fields such as name, website, location, and number of locations.
All request parameters
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.
# Search Businesses
## Endpoint
POST https://api.openmart.ai/api/v1/search
## Description
Search and retrieve Openmart business records by keyword, location, and business attributes. Use this endpoint to build lead lists, find target businesses, or pull business data into your own workflow.
## Authentication
Header: `X-API-Key: <your_api_key>`
## Example Request
```bash
curl -X POST "https://api.openmart.ai/api/v1/search" \
-H "Accept: application/json" \
-H "X-API-Key: <your_api_key>" \
-H "Content-Type: application/json" \
-d '{
"query": "hair salons",
"location": [{"country": "USA", "state": "CA", "city": "San Francisco"}],
"has_website": true,
"has_valid_website": true,
"has_contact_info": true
}'
```
## Parameters
### Most common parameters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| query | string | No | Primary free-text search (1–500 chars). Ignored when tags is non-empty. |
| limit | integer | No | Page size: 1–1000. Recommended 100. Preview keys must be ≤100. |
| location | array[object] | No | Geographic filters. Array of Location objects. |
| has_website | boolean | No | Only businesses that have any website URL. |
| has_valid_website | boolean | No | Only businesses with a validated website URL. |
| has_contact_info | boolean | No | Only businesses that have contact-related signals. |
| tags | array[string] | No | Search by tag labels (up to 100). If non-empty, tag-based matching replaces query. |
| store_name | string | No | Filter or boost by store name. |
| min_locations | integer | No | Minimum number of locations for the brand. |
### Location object fields
| Name | Type | Required | Description |
|------|------|----------|-------------|
| country | string | No | Country code or name. Defaults to US. |
| state | string | No | State or region name. |
| city | string | No | City name filter. |
| zip_code | array[string] | No | One or more postal/ZIP codes. |
| lat | number | No | Latitude (WGS84), paired with long for radius search. |
| long | number | No | Longitude (WGS84), paired with lat for radius search. |
| geo_radius | integer | No | Radius in meters around lat/long. |
| use_geo_fuzz | boolean | No | If true, prefer radius/geo behavior over city/state/zip. |
### Business quality and scale filters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| min_overall_rating | number | No | Minimum Google-style overall rating (0–5). |
| max_overall_rating | number | No | Maximum Google-style overall rating (0–5). |
| min_total_reviews | integer | No | Minimum total review count. |
| max_total_reviews | integer | No | Maximum total review count. |
| min_price_tier | integer | No | Minimum price tier. |
| max_price_tier | integer | No | Maximum price tier. |
| max_locations | integer | No | Maximum number of locations for the brand. |
| ownership_type | string | No | Filter by ownership classification. |
### Keyword and domain filters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| include_keywords | array[string] | No | Businesses whose text should mention these terms (up to 64). |
| exclude_keywords | array[string] | No | Businesses whose text must not mention these terms (up to 64). |
| exclude_root_domains | array[string] | No | Exclude businesses with these root domains. |
### Time-based filters
| Name | Type | Required | Description |
|------|------|----------|-------------|
| open_date_after | string | No | Only businesses opened on or after this ISO 8601 date. |
| open_date_before | string | No | Only businesses opened on or before this ISO 8601 date. |
| info_updated_after | string | No | Lower bound on last info refresh time. |
| info_updated_before | string | No | Upper bound on last info refresh time. |
### Pagination and response shape
| Name | Type | Required | Description |
|------|------|----------|-------------|
| cursor | array | No | Opaque pagination token: [match_score, store_id]. Omit for first page, reuse last result's cursor for next page. |
| estimate_total | boolean | No | If true, response wraps as {data, total_count}. |
## Example Response
```json
[
{
"id": "54ff8cd5-7497-4f46-9c0c-c6b8c0d10d04",
"content": {
"business_name": "Curls are Fun",
"store_name": "Curls Are Fun",
"root_domain": "antonioberducci.com",
"website_url": "http://www.antonioberducci.com/",
"city": "San Francisco",
"state": "California",
"country": "US",
"street_address": "300 Divisadero St",
"zipcode": "94117",
"store_phones": ["+14156264782"],
"google_rating": 5,
"google_reviews_count": 1,
"tags": ["beauty salon", "hair salon", "hair care service"],
"business_categories": ["BEAUTY_PERSONAL_CARE"],
"num_stores": 4,
"latitude": 37.7723988,
"longitude": -122.4370998
},
"match_score": 24.264505,
"match_highlights": ["hair salon", "hair care service", "hairdresser"],
"cursor": [24.264505, "54ff8cd5-7497-4f46-9c0c-c6b8c0d10d04"]
}
]
```