External API docs

Search business IDs (fast)

Run a lightweight search that returns only IDs, place IDs, scores, and cursors — ideal for paging over large result sets before hydrating the rows you care about.

Overview

This endpoint is a lightweight sibling of POST /api/v1/search. It takes the same request body but returns only id, place_id, match_score, and cursor per hit — no full business content.

Use it for a fast first pass over large result sets, then hydrate the rows you want via GET /api/v1/business_records/list/openmart_id. Each returned row is billed at a reduced rate compared to full /api/v1/search.

Before you start

Make sure you have:

  • an Openmart account
  • an API key
  • a tool to send API requests, such as Postman or curl

Authentication: send your key in the X-API-Key header. Authorization: Bearer <key> is also accepted.

1

Example: Fast search for hair salons in San Francisco

Endpoint
POST https://api.openmart.ai/api/v1/search/only_ids

cURL request

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

Response example (estimate_total omitted / false)

JSON
[
  {
    "id": "22d72ba0-5e83-49f5-a206-b995bb325c61",
    "place_id": "ChIJvaSLfjl-j4ARG0uVkryFc54",
    "match_score": 44.12081,
    "cursor": [44.12081, "22d72ba0-5e83-49f5-a206-b995bb325c61"]
  },
  {
    "id": "22e83829-a2d9-401d-9dd7-74f07be0ce03",
    "place_id": "ChIJNxavPmKAhYARCL62hdTBzvs",
    "match_score": 44.12081,
    "cursor": [44.12081, "22e83829-a2d9-401d-9dd7-74f07be0ce03"]
  }
]

Response example (estimate_total=true)

JSON
{
  "data": [
    {
      "id": "0191ea2e-b0fb-43c0-9bd7-5735ffa869df",
      "place_id": "ChIJrRh2LBfkmoARy__PdBymsN4",
      "match_score": 44.12081,
      "cursor": [44.12081, "0191ea2e-b0fb-43c0-9bd7-5735ffa869df"]
    }
  ],
  "total_count": 29644
}

Key elements of the API response

Response element
id
Description
Openmart business ID (UUID). Feed this to GET /api/v1/business_records/list/openmart_id to hydrate the full record.
Response element
place_id
Description
Google Place ID when the record has a Google Maps source; empty string otherwise.
Response element
match_score
Description
Relevance score from the underlying search index.
Response element
cursor
Description
[match_score, id] — reusable as the cursor parameter on POST /api/v1/search for deterministic pagination.
Response element
data[] + total_count
Description
When estimate_total=true, the response is wrapped as { data, total_count }. Otherwise the top-level value is the raw array of rows above.

Pass the returned id values to GET /api/v1/business_records/list/openmart_id to hydrate the rows you want.

All request parameters

The request body for POST /api/v1/search/only_ids is identical to POST /api/v1/search — same fields, same validators, same shape. For the full parameter list (with grouped examples), see Search businesses → All request parameters.

# Search Business IDs (Fast)

## Endpoint

POST https://api.openmart.ai/api/v1/search/only_ids

## Description

Lightweight search that returns IDs and cursors first, then you can fetch full business records with the detail endpoint. Uses the same request body schema as POST /api/v1/search.

## Authentication

Header: `X-API-Key: <your_api_key>`

## Example Request

```bash
curl -X POST "https://api.openmart.ai/api/v1/search/only_ids" \
  -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"}],
    "limit": 20
  }'
```

## Example Response

```json
[
  {
    "id": "f7f7f5b7-1111-2222-3333-123456789abc",
    "place_id": "ChIJ123abcXYZ",
    "match_score": 0.93,
    "cursor": [0.93, "f7f7f5b7-1111-2222-3333-123456789abc"]
  }
]
```

Use the returned `id` values with GET /api/v1/business_records/list/openmart_id to fetch full records.