Documentation
API Documentation
discava REST API – Search for local businesses worldwide
Base URL
https://discava.ai/api/v1No authentication required. Rate limited to 500 requests per hour per IP.
SKILL.md
Add discava as a skill to your AI agent or chatbot.
MCP Server (Remote)
Connect your AI agent directly via the Model Context Protocol.
MCP Server (Local)
Download, extract, run npm install && npx tsx server.ts
Scores
confidence_score (0–100)
Data quality score. Measures how complete and verified a business listing is (address, phone, website, opening hours, etc.).
demand_score (0–100)
Ranking score based on click-through rate. Calculated using Wilson's Lower Bound — a statistical method that estimates the true popularity of a business based on how often it is clicked relative to how often it appears in search results.
relevance_score (0.0–1.0)
Query-specific score returned with search results. Combines text match, quality signals, proximity, and data completeness.
Response Format
Every response follows this structure:
{
"success": true,
"data": { ... },
"meta": {
"request_id": "req_abc123"
}
}Endpoints
/api/v1/search
Search for businesses. Returns results sorted by relevance score. Supports pagination.
Parameters
| Name | Required | Description |
|---|---|---|
q | No | Search query (category name, business name, or keyword) |
city | No | City name (e.g. MĂĽnchen, Hamburg) |
country | Yes | ISO country code (e.g. DE, AT, CH, US) |
category | No | Category slug directly (e.g. plumber, restaurant) |
limit | No | 1-50 (default: 20) |
page | No | Page number (default: 1) |
min_confidence | No | Minimum confidence score 0-100 (default: 0) |
lang | No | Language for category labels: de or en (default: de) |
lat, lon | No | Coordinates for distance calculation |
format | No | json (default) or html – returns interactive HTML cards with click tracking |
Example
curl "https://discava.ai/api/v1/search?q=Klempner&city=Hamburg&country=DE&limit=1"
Response
{
"success": true,
"data": {
"results": [{
"id": "abc123",
"name": "Klempner MĂĽller",
"slug": "klempner-mueller-hamburg",
"category": "plumber",
"category_label": "Klempner",
"parent_category": "craftsman",
"parent_category_label": "Handwerker",
"city": "Hamburg",
"country": "DE",
"logo_url": "https://www.google.com/s2/favicons?domain=klempner-mueller.de&sz=64",
"available_details": ["phone", "website", "opening_hours", "services"],
"confidence_score": 65,
"demand_score": 28,
"relevance_score": 0.82
}],
"total": 44,
"page": 1,
"total_pages": 44,
"limit": 1
},
"meta": { "request_id": "req_abc123" }
}
Check available_details to see what data exists,
then call GET /api/v1/business/{id} for full details./api/v1/business/:id
Get full details for one or more businesses: address, phone, website, opening hours, services, payment methods, social links, logo, business image, and coordinates. Supports comma-separated IDs for batch requests. Add ?format=html for interactive HTML cards with click tracking.
# Single business
curl "https://discava.ai/api/v1/business/{id}"
# Batch (multiple IDs)
curl "https://discava.ai/api/v1/business/{id1},{id2},{id3}"/api/v1/feedback
Report data quality issues. Feedback is stored for monitoring but does not affect ranking scores. Only business_id and type are required. Use comment to describe the issue.
curl -X POST "https://discava.ai/api/v1/feedback" \
-H "Content-Type: application/json" \
-d '{"business_id":"xxx","type":"PHONE_INVALID","comment":"Number disconnected"}'Feedback Types
/api/v1/ranking
Top businesses by Demand Score (based on click-through rate). Filter by category, city, or country.
curl "https://discava.ai/api/v1/ranking?category=plumber&city=Hamburg&limit=10"
/api/v1/suggest
Autocomplete suggestions for cities, categories, and business names. Useful for resolving user input before searching.
Parameters
| Name | Required | Description |
|---|---|---|
q | Yes | Query (min. 2 characters) |
type | No | city or query (default: query) |
limit | No | 1-15 (default: 10) |
curl "https://discava.ai/api/v1/suggest?type=city&q=MĂĽn" curl "https://discava.ai/api/v1/suggest?type=query&q=Klemp"
/api/v1/health
Health check endpoint. Returns status and version.