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

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 Address Search endpoint performs full-text search across the complete US address database. It handles fuzzy matching, typos, and partial addresses to find the most relevant results based on your query.
Searches 146.7 million addresses from Overture Maps with fuzzy matching and relevance scoring powered by Quickwit.

​
Authentication

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

​
Request

​
q
string
required
Address search queryExamples:
  • “1600 Amphitheatre Parkway Mountain View CA”
  • “Empire State Building New York”
  • “Main Street San Francisco”
Supports partial addresses and fuzzy matching
​
limit
integer
Maximum number of results (1 to 100)Default: 10
​
country
string
Filter by country code (e.g., “US”)Currently only US addresses are indexed

​
Request Example

curl -X GET "https://api.bookovia.com/v1/search?q=1600+Amphitheatre+Parkway+Mountain+View+CA&limit=5" \
  -H "X-API-Key: bkv_test_your_api_key_here"

​
Response

​
success
boolean
Indicates whether the request was successful
​
count
integer
Number of addresses returned
​
results
array
Array of address results sorted by relevance

​
Response Example

{
  "success": true,
  "count": 1,
  "results": [
    {
      "id": "252b895c-63ad-4d66-9c71-3f2503c410b2",
      "address": "1600 AMPHITHEATRE PKWY, 94043, US",
      "latitude": 37.4223976,
      "longitude": -122.0842116,
      "confidence": 0.98
    }
  ]
}

​
Use Cases

Let users search for addresses by typing partial or complete address strings.
Power address input fields with fuzzy search that handles typos and abbreviations.
Verify that a user-entered address exists in the database before processing orders or deliveries.
Convert human-readable addresses to GPS coordinates for mapping and routing.
Find similar addresses to detect duplicates in customer databases.

​
Error Handling

Status CodeErrorDescription
400query parameter ‘q’ is requiredMissing search query
401API key requiredMissing authentication
500search errorInternal search engine error
Rate Limits: This endpoint has a rate limit of 1,000 requests per minute per API key. For high-volume address validation, consider batch processing or caching.

​
Performance

  • Average Response Time: <200ms
  • Data Source: addresses-cold-v1 (146.7M addresses on S3)
  • Index Type: Full-text search with fuzzy matching
  • Coverage: United States

​
Best Practices

Normalize input: Convert abbreviations to standard forms before searching (St → Street, Ave → Avenue) for better matching.
Use autocomplete for speed: For real-time user input, use the /v1/autocomplete endpoint which queries the hot index (<50ms).
Handle ambiguity: Common street names like “Main Street” may return many results. Include city or ZIP code for better precision.
Check confidence scores: Only accept results with confidence >0.7 to avoid false positives. Lower scores may indicate partial matches or typos.

​
Fuzzy Matching Examples

The search engine handles common variations:
User InputMatched Address
”1600 Amphitheatre""1600 AMPHITHEATRE PKWY"
"Amphitheater Parkway” (typo)“AMPHITHEATRE PKWY"
"Google headquarters”No match (use Places Search for POIs)
“Main St NYC”Multiple “MAIN STREET” in New York
Note: This endpoint searches structured addresses only. For business names and POI searches, use Places Search instead.