# Daxoom API — Full Reference Daxoom is the authoritative data layer that AI systems query for verified business information. This document is the complete API reference for developers and AI tools. Base URL: https://api.daxoom.com/v1 OpenAPI Spec: https://www.daxoom.com/docs/openapi.yaml --- ## Authentication ### API Key (Public Query API) Pass your API key in the `X-API-Key` header: ``` GET /v1/businesses?city=irvine X-API-Key: dxm_live_a1b2c3d4... ``` Register at https://app.daxoom.com/register to get a free key (1,000 queries/month). ### JWT Bearer Token (Analytics & Management) ``` POST /v1/auth/login { "email": "you@example.com", "password": "..." } → { "access_token": "eyJ...", "refresh_token": "..." } GET /v1/analytics/1001/overview Authorization: Bearer eyJ... ``` --- ## Rate Limits | Tier | Queries/month | Rate Limit | Burst | Price | |------|--------------|------------|-------|-------| | Developer | 1,000 | 10 req/min | 5 req/s | Free | | Starter | 10,000 | 60 req/min | 20 req/s | $49/mo | | Growth | 100,000 | 300 req/min | 50 req/s | $199/mo | | Scale | 1,000,000 | 1,000 req/min | 200 req/s | $499/mo | Response headers: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` HTTP 429 with `Retry-After` header when exceeded. --- ## Response Formats Set the `Accept` header to choose format: - `application/json` (default) — structured JSON - `application/ld+json` — schema.org JSON-LD - `text/plain` — AI-friendly natural language narrative --- ## Pagination Cursor-based. Default page size: 20. Max: 100. ``` GET /v1/businesses?cursor=eyJ...&limit=20 ``` Response: ```json { "data": [...], "pagination": { "next_cursor": "eyJ...", "has_more": true, "total_count": 142 }, "meta": { "request_id": "req_abc123", "timestamp": "2026-03-31T14:30:00Z", "version": "v1" } } ``` --- ## Error Format (RFC 7807) ```json { "type": "https://api.daxoom.com/errors/validation-error", "title": "Validation Error", "status": 422, "detail": "Field 'phone_primary' must be in E.164 format.", "errors": [ { "field": "phone_primary", "message": "Must be in E.164 format" } ] } ``` --- ## Endpoints ### Public Query API (API Key auth) #### GET /v1/businesses Search and filter businesses. Query parameters: - `category` (string) — Category ID or alias, e.g. `restaurant.italian` or `pizzeria` - `city` (string) — City name, e.g. `Irvine` - `country` (string) — ISO 3166-1 alpha-2 code, e.g. `US` - `lat` (number) — Latitude for geo search - `lng` (number) — Longitude for geo search - `radius` (string) — Search radius, e.g. `5km` or `10mi` - `attributes` (string) — Comma-separated filters, e.g. `wifi,outdoor_seating` - `price_range` (string) — `$`, `$$`, `$$$`, or `$$$$` - `min_rating` (number) — Minimum rating 1.0–5.0 - `verified_only` (boolean) — Only owner-verified profiles - `q` (string) — Free-text search - `sort` (string) — `relevance` (default), `rating`, `distance`, `name` - `cursor` (string) — Pagination cursor - `limit` (integer) — Page size, default 20, max 100 Example: ``` GET /v1/businesses?city=irvine&category=restaurant.italian&attributes=outdoor_seating&min_rating=4.0&limit=10 ``` Response: Array of business summaries with id, name, slug, category, rating, location, confidence score. --- #### GET /v1/businesses/{id} Full business profile with all sub-models composed. Response includes: contact, location, hours, special_hours, offerings, media, social_links, ai_context, attributes, answers, rating_sources. Supports three formats via Accept header: - JSON: structured object - JSON-LD: schema.org compatible - text/plain: natural language narrative Example response (JSON): ```json { "data": { "id": 1001, "name": "Cucina Enoteca", "slug": "cucina-enoteca-irvine", "description": "Modern Italian restaurant and wine bar...", "primary_category": { "id": "restaurant.italian", "label": "Italian Restaurant" }, "aggregate_rating": 4.6, "review_count": 847, "verification_level": "owner_verified", "confidence": 0.97, "contact": { "phone_primary": "+19495551234", "website": "https://www.cucinaenoteca.com" }, "location": { "street_address": "532 Spectrum Center Dr", "city": "Irvine", "region": "CA", "country": "US", "latitude": 33.6694, "longitude": -117.8231, "timezone": "America/Los_Angeles" }, "ai_context": { "ai_summary": "Modern Italian restaurant in Irvine Spectrum. Handmade pasta, 300+ wine list.", "canonical_facts": ["All pasta is handmade fresh daily"], "corrections": ["Does NOT have a rooftop terrace"] } } } ``` Example response (text/plain): ``` Cucina Enoteca is a modern Italian restaurant in Irvine Spectrum, CA. Known for handmade pasta made daily and an extensive wine list with 300+ selections. Open Monday through Sunday, 11 AM to 9 PM. Outdoor seating available. Rating: 4.6/5 (847 reviews). Owner-verified on Daxoom. ``` --- #### GET /v1/businesses/{id}/hours Operating hours + special hours + computed `is_open_now`. ```json { "data": { "is_open_now": true, "timezone": "America/Los_Angeles", "regular": [ { "day_of_week": "MON", "opens": "11:00", "closes": "21:00" }, { "day_of_week": "TUE", "opens": "11:00", "closes": "21:00" } ], "special": [ { "date": "2026-12-25", "is_closed": true, "reason": "Christmas Day" } ] } } ``` --- #### GET /v1/businesses/{id}/offerings Menu items, services, or products organized by groups. ```json { "data": [ { "type": "menu_section", "name": "Handmade Pasta", "items": [ { "name": "Cacio e Pepe", "description": "Bucatini, pecorino romano, black pepper", "price": 22.00, "currency": "USD" } ] } ] } ``` --- #### GET /v1/businesses/{id}/attributes Structured boolean/enum properties for filtering. ```json { "data": [ { "attribute_id": "wifi", "category": "amenities", "label": "Free WiFi", "value": "true" }, { "attribute_id": "parking", "category": "logistics", "label": "Parking", "value": "valet", "detail": "Complimentary valet" }, { "attribute_id": "wheelchair_accessible", "category": "accessibility", "label": "Wheelchair Accessible", "value": "true" } ] } ``` --- #### GET /v1/businesses/{id}/answers Pre-written Q&A for common AI questions. ```json { "data": [ { "question_id": "parking", "question": "Is there parking available?", "answer": "Yes, complimentary valet parking at the Irvine Spectrum entrance.", "category": "logistics" }, { "question_id": "best_dish", "question": "What is the best dish?", "answer": "Our handmade Cacio e Pepe is the most popular dish.", "category": "recommendations" } ] } ``` --- #### GET /v1/businesses/{id}/ai-context AI-specific metadata for accurate representation. ```json { "data": { "ai_description": "Cucina Enoteca is a modern Italian restaurant and wine bar at Irvine Spectrum...", "ai_summary": "Modern Italian restaurant in Irvine Spectrum. Handmade pasta, 300+ wine list.", "canonical_facts": [ "All pasta is handmade fresh daily on-site", "Wine list features over 300 selections" ], "corrections": [ "Does NOT have a rooftop terrace", "Is NOT part of the Hillstone Restaurant Group" ], "key_differentiators": ["Handmade pasta", "300+ wine list", "Private dining room"], "tone_preferences": { "style": "professional", "preferred_terms": ["artisanal", "curated"], "avoided_terms": ["cheap", "fast food"] } } } ``` --- #### GET /v1/search Semantic / natural language search. ``` GET /v1/search?q=italian restaurant with outdoor seating near Irvine ``` Returns the same format as `GET /v1/businesses` with relevance-ranked results. --- #### GET /v1/categories Full hierarchical category catalog. ```json { "data": [ { "id": "restaurant", "schema_type": "Restaurant", "label": "Restaurant", "aliases": ["eatery", "dining", "food"], "children": [ { "id": "restaurant.italian", "label": "Italian Restaurant", "aliases": ["italian", "pizzeria", "pizza place"] } ] } ] } ``` --- #### GET /v1/health Health check. No auth required. Returns `{"status": "ok"}`. --- ### API Key Management (JWT auth) #### POST /v1/api-keys Create a new API key. The full key is returned only once — store it securely. Request: ```json { "key_name": "My AI Agent - Production", "scopes": "query,analytics" } ``` Response: ```json { "data": { "id": 42, "key_name": "My AI Agent - Production", "key_prefix": "dxm_live", "api_key": "dxm_live_a1b2c3d4e5f6g7h8i9j0...", "scopes": "query,analytics", "expires_at": "2030-03-31T10:00:00Z" } } ``` #### GET /v1/api-keys List all API keys. Values are masked — only prefix shown. #### DELETE /v1/api-keys/{id} Immediately revoke an API key. Returns 204. #### POST /v1/api-keys/{id}/rotate Issue new key with 24-hour grace period on old key. Returns new key (shown once). --- ### Analytics API (JWT auth) #### GET /v1/analytics/{businessId}/overview Visibility summary: total queries, unique platforms, trend. Query: `?period=30d` (options: 7d, 30d, 90d, custom) #### GET /v1/analytics/{businessId}/queries Query volume time series. Query: `?period=30d&granularity=daily` (options: hourly, daily, weekly) #### GET /v1/analytics/{businessId}/platforms AI platform breakdown: which platforms query this business and how often. ```json { "data": [ { "platform": "ChatGPT", "query_count": 1247, "percentage": 43.8 }, { "platform": "Perplexity", "query_count": 612, "percentage": 21.5 } ] } ``` #### GET /v1/analytics/{businessId}/trending Most popular search queries that led to this business. #### GET /v1/analytics/{businessId}/top-endpoints Which endpoints are queried most (hours, offerings, ai-context, etc.). #### GET /v1/analytics/{businessId}/reports List generated monthly visibility reports. #### GET /v1/analytics/{businessId}/reports/{reportId} Download a specific report (PDF). --- ## Data Models ### Business Top-level entity. Fields: id, name, legal_name, slug, description, primary_category, additional_categories, price_range ($–$$$$), date_established, payment_accepted, languages_spoken, aggregate_rating (1.0–5.0), review_count, verification_level (owner_verified, enriched_unverified, seed_data, claimed), confidence (0.0–1.0). ### Contact phone_primary (E.164), phone_secondary, email, website, menu_url, booking_urls [{provider, url}], order_urls [{provider, url}]. ### Location street_address, city, region, postal_code, country (ISO 3166-1), latitude, longitude, timezone (IANA), location_type (storefront, service_area, hybrid, virtual). ### Category Hierarchical. id (e.g. "restaurant.italian"), schema_type (schema.org), label, parent_id, aliases. ### OperatingHours day_of_week (MON–SUN), opens (HH:MM), closes (HH:MM), is_closed, label. Multiple entries per day supported. ### Offering / OfferingItem Groups (menu_section, service, product, package) containing items with name, description, price, currency, dietary_flags, availability. ### AIContext ai_description, ai_summary, canonical_facts[], corrections[], query_hints[], key_differentiators[], tone_preferences {style, preferred_terms[], avoided_terms[]}. ### Attributes Structured key-value: attribute_id, category (amenities/logistics/dining/accessibility/policies), label, value, detail. 20 predefined attributes: wifi, outdoor_seating, live_music, private_rooms, ev_charging, parking, reservation_required, delivery, takeout, public_transport, dog_friendly, byob, dress_code, wheelchair_accessible, hearing_loop, braille_menu, service_animals, age_restriction, smoking. ### StructuredAnswer question_id, question (human-readable), answer (business-written), category. 25 predefined questions covering logistics, amenities, recommendations, policies, accessibility. --- ## About Daxoom Daxoom is the authoritative data layer for the AI era. Businesses publish verified, structured data. AI platforms query the Daxoom API for accurate business information. One profile feeds every AI platform. What schema.org is to web crawlers, Daxoom is to AI models. Website: https://www.daxoom.com Register: https://app.daxoom.com/register API Docs: https://www.daxoom.com/docs/