Search Businesses

GET/api/v1/search/businesses

Overview

Search businesses from SpiderMaps results with full-text search, geo-distance filtering, and faceted results.

Use cases: VayaPin restaurant search, Gun Guard retailer finder, local business directories.

Authentication

Authorizationstringrequired

Bearer token in format: Bearer client_id:api_key:api_secret

Query Parameters

querystring

Search query for full-text search on name, description, category. Max 500 characters.

categorystring

Filter by business category (e.g., "restaurant", "coffee shop").

min_ratingnumber

Minimum rating filter. Range: 0-5.

latnumber

Latitude for geo search. Range: -90 to 90.

lonnumber

Longitude for geo search. Range: -180 to 180.

radius_kmintegerdefault: 50

Search radius in kilometers. Range: 1-500.

pageintegerdefault: 1

Page number for pagination.

per_pageintegerdefault: 20

Results per page. Range: 1-100.

sort_bystringdefault: _score

Sort field. Options: _score, rating, reviews_count, newest.

Response

successboolean

Whether the request was successful.

totalinteger

Total number of matching documents.

hitsarray

Array of search results.

Hit object

doc_idstring

Document ID.

scorenumber

Relevance score.

namestring

Business name.

categorystring

Business category.

ratingnumber

Business rating (0-5).

reviews_countinteger

Number of reviews.

addressstring

Business address.

phonestring

Phone number.

websitestring

Website URL.

emailstring

Email address.

locationobject

Geo coordinates with lat and lon fields.

facetsobject

Aggregated facets for filtering.

Facets object

categoriesarray

Category facets with name and count.

rating_rangesarray

Rating range facets.

avg_ratingnumber

Average rating across results.

pageinteger

Current page number.

per_pageinteger

Results per page.

Examples

Request Example

curl -X GET "https://spideriq.ai/api/v1/search/businesses?query=coffee" \
  -H "Authorization: Bearer cli_xxx:key:secret"

curl -X GET "https://spideriq.ai/api/v1/search/businesses?query=restaurant&lat=49.6117&lon=6.1319&radius_km=10" \
  -H "Authorization: Bearer cli_xxx:key:secret"

curl -X GET "https://spideriq.ai/api/v1/search/businesses?category=restaurant&min_rating=4&sort_by=rating" \
  -H "Authorization: Bearer cli_xxx:key:secret"

Response Example

{
  "success": true,
  "total": 156,
  "hits": [
    {
      "doc_id": "abc123",
      "score": 8.5,
      "name": "Café Central",
      "category": "Coffee Shop",
      "rating": 4.7,
      "reviews_count": 234,
      "address": "12 Grand Rue, Luxembourg",
      "phone": "+352 123 456",
      "website": "https://cafecentral.lu",
      "email": "info@cafecentral.lu",
      "location": {
        "lat": 49.6117,
        "lon": 6.1319
      }
    }
  ],
  "facets": {
    "categories": [
      {"name": "Coffee Shop", "count": 45},
      {"name": "Café", "count": 32}
    ],
    "avg_rating": 4.2
  },
  "page": 1,
  "per_page": 20
}