Browse API docsSearch business IDs (fast)
External API docs

Search business IDs (fast)

Search quickly for IDs, place IDs, scores, and next-page cursors, then fetch full details only for the businesses you need.

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. We recommend sending your API key as Authorization: Bearer <your_api_key>. If your current integration already uses X-API-Key: <your_api_key>, it will continue to work.

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 'Authorization: Bearer <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.

If this request fails

Match the error number or message in the response, then use the action below.

Error 400 / 422“... is required” or another field error
Read the error or detail field, then fix the named input.
Error 401“Invalid API Key”
Check the complete key and authentication header.
Error 402“Credit limit reached”
Check the team balance before trying again.
Error 403“Forbidden” or “not allowed”
Check whether this key and account can use the action.
Error 404“Not Found”
Check the API address, version, and GET, POST, or DELETE method.
Error 429“Too many requests”
Wait, then retry with fewer requests running at once.
Error 500–504Server error or timeout
Wait briefly and retry. Avoid duplicating an async job.

See Troubleshooting & FAQ for step-by-step help and the information to include when asking for support.