Skip to main content
GET
/
v1
/
validate
Validate Address
curl --request GET \
  --url https://api.bookovia.com/v1/validate \
  --header 'X-API-Key: <api-key>'
{
  "success": true,
  "exists": true,
  "id": "<string>",
  "address": "<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 Validate Address endpoint provides a lightweight boolean check for address existence. It returns true/false based on whether the address is found in the database with a confidence score above 0.7.
Fast validation endpoint for form submission, order processing, and data quality checks.

​
Authentication

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

​
Request

​
q
string
required
Address string to validateShould be a reasonably complete address for accurate validation

​
Request Example

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

​
Response

​
success
boolean
Indicates whether the request was successful
​
exists
boolean
True if address exists with confidence >0.7, false otherwise
​
id
string
Address identifier (only present if exists = true)
​
address
string
Standardized address text (only present if exists = true)

​
Response Example (Address Found)

{
  "success": true,
  "exists": true,
  "id": "252b895c-63ad-4d66-9c71-3f2503c410b2",
  "address": "1600 AMPHITHEATRE PKWY, 94043, US"
}

​
Response Example (Address Not Found)

{
  "success": true,
  "exists": false
}

​
Use Cases

Validate user-entered addresses before form submission to reduce errors.
Verify delivery addresses exist before accepting orders or scheduling deliveries.
Clean up customer databases by flagging invalid or non-existent addresses.
Add address validation to third-party forms, CRMs, or e-commerce platforms.
Flag suspicious orders with invalid addresses for fraud prevention.

​
Confidence Threshold

The endpoint uses a confidence score of 0.7 as the validation threshold:
  • Score ≥ 0.7: Address exists (returns true)
  • Score < 0.7: Address not found or low confidence match (returns false)
This threshold balances:
  • ✅ Accepting real addresses with minor variations
  • ❌ Rejecting typos and non-existent addresses
For stricter validation, use the Address Search endpoint and check confidence scores manually.

​
Error Handling

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

​
Performance

  • Average Response Time: <150ms
  • Data Source: addresses-cold-v1 (146.7M addresses)
  • Confidence Threshold: 0.7

​
Best Practices

Provide feedback: When validation fails, show the user what address format is expected or suggest corrections using the autocomplete endpoint.
Normalize first: Clean and standardize the address string before validating (trim whitespace, uppercase, remove special characters).
Batch validation: If validating many addresses, consider caching results or processing in batches during off-peak hours.
Handle edge cases: Some valid addresses may not be in the database (new constructions, rural routes). Provide a manual override option.

​
Example: Form Validation Flow

JavaScript
async function validateAddressField(addressInput) {
  const address = addressInput.value.trim();
  
  if (address.length &lt; 10) {
    showError('Address too short');
    return false;
  }
  
  const response = await fetch(
    `https://api.bookovia.com/v1/validate?q=${encodeURIComponent(address)}`,
    {
      headers: { 'X-API-Key': 'bkv_your_key' }
    }
  );
  
  const data = await response.json();
  
  if (data.exists) {
    showSuccess(`Valid address: ${data.address}`);
    // Optionally auto-fill standardized address
    addressInput.value = data.address;
    return true;
  } else {
    showError('Address not found in database. Please check and try again.');
    return false;
  }
}

// Usage in form submission
document.getElementById('checkout-form').addEventListener('submit', async (e) => {
  e.preventDefault();
  
  const addressInput = document.getElementById('address');
  const isValid = await validateAddressField(addressInput);
  
  if (isValid) {
    // Proceed with order
    submitOrder();
  }
});

​
Limitations

Not USPS certified: This endpoint validates against Overture Maps data, not official USPS records. For USPS-level validation, use a dedicated address verification service.

​
Known Limitations:

  • New addresses (<1 month old) may not be in database
  • Rural routes and PO boxes have limited coverage
  • Apartment/unit numbers may not match exactly
  • Address format variations may cause false negatives

​
When to Use Each Endpoint

Use CaseRecommended Endpoint
Quick boolean checkValidate (this endpoint)
Get standardized formatAddress Search
Real-time user inputAutocomplete
Fuzzy matchingAddress Search