Skip to main content
GET
/
v1
/
places
/
search
Search Places
curl --request GET \
  --url https://api.bookovia.com/v1/places/search \
  --header 'X-API-Key: <api-key>'
{
  "success": true,
  "count": 123,
  "places": [
    {
      "id": "<string>",
      "name": "<string>",
      "category": "<string>",
      "latitude": 123,
      "longitude": 123,
      "address": "<string>",
      "distance_km": 123,
      "confidence": 123
    }
  ],
  "error": "<string>"
}

Documentation Index

Fetch the complete documentation index at: https://docs.bookovia.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

The Places Search endpoint provides powerful text-based search across 19.7 million points of interest including businesses, landmarks, and public facilities. It supports spatial filtering to prioritize results near a specific location and category filtering to narrow results by type.
Built on Overture Maps data with 19.7M+ POIs including restaurants, shops, hotels, and landmarks across the United States.

​
Authentication

This endpoint requires authentication via API key in the X-API-Key header. Required permissions: geocoding:read

​
Request

​
q
string
required
Search query text (e.g., “starbucks”, “pizza near me”, “hotels”)Supports fuzzy matching and partial text search
​
lat
number
Center point latitude for spatial ranking (-90 to 90)When provided with lon, results are sorted by relevance and proximity
​
lon
number
Center point longitude for spatial ranking (-180 to 180)Required if lat is provided
​
radius
number
Search radius in kilometers (0.1 to 100)Only returns results within this distance from center pointDefault: 50
​
categories
string
Filter by category (e.g., “restaurant”, “coffee_shop”, “hotel”)Multiple categories not supported (use separate requests)
​
limit
integer
Maximum number of results to return (1 to 100)Default: 20

​
Request Example

curl -X GET "https://api.bookovia.com/v1/places/search?q=starbucks&lat=40.7128&lon=-74.0060&radius=5&limit=10" \
  -H "X-API-Key: bkv_test_your_api_key_here"

​
Response

​
success
boolean
Indicates whether the request was successful
​
count
integer
Number of places returned in this response
​
places
array
Array of place objects matching the search criteria

​
Response Example

{
  "success": true,
  "count": 10,
  "places": [
    {
      "id": "018a9083-401f-4207-b450-c8ff39626513",
      "name": "Starbucks",
      "category": "coffee_shop",
      "latitude": 40.7128,
      "longitude": -74.0060,
      "address": "123 Broadway, New York, NY 10001",
      "distance_km": 0.5,
      "confidence": 0.95
    },
    {
      "id": "018a9083-5b2a-4c19-a320-8f1234567890",
      "name": "Starbucks Reserve",
      "category": "coffee_shop",
      "latitude": 40.7145,
      "longitude": -74.0072,
      "address": "456 5th Ave, New York, NY 10018",
      "distance_km": 1.2,
      "confidence": 0.92
    }
  ]
}

​
Use Cases

Find nearby businesses and attractions for travel and discovery apps. Show users relevant places near their current location.
Help users plan routes with POI stops. Find restaurants, rest areas, and attractions along a route.
Build recommendation engines that suggest places based on user preferences and location.
Find pickup/dropoff locations for delivery apps. Search for restaurants, stores, and service locations.

​
Error Handling

​
error
string
Error message if the request failed

​
Common Errors

Status CodeErrorDescription
400query parameter ‘q’ is requiredMissing search query
400Invalid radiusRadius must be between 0.1 and 100 km
401API key requiredMissing X-API-Key header
401Invalid API key formatAPI key doesn’t start with bkv_
500search errorInternal search engine error
Rate Limits: This endpoint has a rate limit of 1,000 requests per minute per API key. Exceeding this limit will result in 429 Too Many Requests responses.

​
Best Practices

Use spatial filtering: Always provide lat and lon when possible to get better relevance ranking based on proximity to the user.
Set appropriate radius: Use smaller radius (1-5km) for dense urban areas, larger radius (10-50km) for rural areas.
Limit results: Request only the number of results you need (5-20) for faster response times.
Category filtering: Use categories parameter to narrow results when you know the type (e.g., only restaurants, only hotels).
Cache results: Cache frequently searched places (e.g., popular chains) to reduce API calls and improve user experience.

​
Performance

  • Average Response Time: <200ms
  • P95 Response Time: <300ms
  • Data Freshness: Monthly updates from Overture Maps
  • Coverage: United States (19.7M+ POIs)