Skip to main content
GET
/
v1
/
autocomplete
Address Autocomplete
curl --request GET \
  --url https://api.bookovia.com/v1/autocomplete \
  --header 'X-API-Key: <api-key>'
{
  "success": true,
  "suggestions": [
    {
      "text": "<string>",
      "latitude": 123,
      "longitude": 123,
      "id": "<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 Autocomplete endpoint provides ultra-fast address suggestions for real-time user input. It queries a hot NVMe-backed index of 145.7 million addresses optimized for type-ahead performance.
Uses addresses-hot-v1 index on NVMe storage for <50ms response times. Optimized for interactive user experiences.

​
Authentication

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

​
Request

​
q
string
required
Partial address string (minimum 3 characters recommended)Examples:
  • “1600 Amp”
  • “Main Street”
  • “94043”
​
limit
integer
Maximum number of suggestions (1 to 20)Default: 5Keep low (5-10) for best performance
​
lat
number
Optional latitude for proximity bias (not implemented in current version)Future enhancement: bias results toward this location
​
lon
number
Optional longitude for proximity bias (not implemented in current version)

​
Request Example

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

​
Response

​
success
boolean
Indicates whether the request was successful
​
suggestions
array
Array of address suggestions sorted by relevance

​
Response Example

{
  "success": true,
  "suggestions": [
    {
      "text": "AMPHITHEATRE PKWY, 94043",
      "latitude": 37.4223976,
      "longitude": -122.0842116,
      "id": "252b895c-63ad-4d66-9c71-3f2503c410b2"
    },
    {
      "text": "AMPHITHEATRE CIR, 94022",
      "latitude": 37.4156789,
      "longitude": -122.0789123,
      "id": "3a7c9183-8f2d-4a19-b431-1e2345678901"
    }
  ]
}

​
Use Cases

Power address input fields with real-time suggestions as users type.
Reduce typing on mobile devices with intelligent address completion.
Help users quickly enter delivery addresses with minimal typing.
Speed up checkout flows with fast address autocomplete.

​
Error Handling

Status CodeErrorDescription
400query parameter ‘q’ is requiredMissing search query
401API key requiredMissing authentication
500search errorInternal search engine error

​
Performance

  • Target Response Time: <50ms
  • P95 Response Time: <100ms
  • Data Source: addresses-hot-v1 (145.7M addresses on NVMe)
  • Optimizations: Prefix search, minimal payload, fast storage
Performance tip: Keep limit at 5-10 suggestions for optimal speed. More results = longer response time.

​
Best Practices

Debounce user input: Wait 300-500ms after user stops typing before calling this endpoint to reduce API calls.
Minimum query length: Only search when user has typed ≥3 characters to avoid too many irrelevant results.
Cache on client: Cache results locally to avoid duplicate queries when user backtracks.
Show loading state: Add a subtle loading indicator during the API call for better UX.
Keyboard navigation: Allow users to navigate suggestions with arrow keys and select with Enter.

​
Example Implementation

import { useState, useEffect } from 'react';

function AddressAutocomplete() {
  const [query, setQuery] = useState('');
  const [suggestions, setSuggestions] = useState([]);
  const [loading, setLoading] = useState(false);

  useEffect(() => {
    if (query.length < 3) {
      setSuggestions([]);
      return;
    }

    const timeoutId = setTimeout(async () => {
      setLoading(true);
      const response = await fetch(
        `https://api.bookovia.com/v1/autocomplete?q=${encodeURIComponent(query)}&limit=5`,
        {
          headers: { 'X-API-Key': 'bkv_your_key' }
        }
      );
      const data = await response.json();
      setSuggestions(data.suggestions || []);
      setLoading(false);
    }, 300); // Debounce 300ms

    return () => clearTimeout(timeoutId);
  }, [query]);

  return (
    <div>
      <input
        type="text"
        value={query}
        onChange={(e) => setQuery(e.target.value)}
        placeholder="Enter address..."
      />
      {loading && <div className="spinner">Loading...</div>}
      {suggestions.length > 0 && (
        <ul className="suggestions">
          {suggestions.map((s) => (
            <li key={s.id} onClick={() => setQuery(s.text)}>
              {s.text}
            </li>
          ))}
        </ul>
      )}
    </div>
  );
}

​
Rate Limiting

High traffic endpoint: This endpoint may receive 10-100x more requests than other endpoints due to keystroke-level calls. Monitor your API usage and implement client-side caching/debouncing.
Recommended limits:
  • Debounce delay: 300-500ms
  • Minimum query length: 3 characters
  • Client-side cache: 5 minutes TTL