POST /v1/search

Search restaurants by dietary query, optional location, and optional user profile.

Request

Field	Type	Notes
query	string	Required. Natural-language restaurant query, maximum 500 characters.
user_profile.diet	enum	Optional preference input such as strict_vegan, vegetarian, or gluten_free. Safety-sensitive and religious-diet inputs are conservative signals, not certification claims.
location	object	Optional lat, lng, and radius_m. Required for near me, nearby, or around me queries. When supplied, returned results stay inside the requested radius. Default radius is 5,000 meters; max is 50,000 meters.
limit	integer	Optional result count. Fast mode defaults to 5 and maxes at 5. Rich mode defaults to 10 and maxes at 50.
include_evidence	boolean	Optional. Defaults to true.

Use rich mode when you need fuller evidence and dimensions.

$headers = @{
  "X-Compass-API-Key" = $env:COMPASS_API_KEY
  "X-Compass-Mode" = "rich"
}

$body = @'
{
  "query": "strict vegan ramen near Brooklyn",
  "user_profile": {
    "diet": "strict_vegan"
  },
  "location": {
    "lat": 40.6782,
    "lng": -73.9442,
    "radius_m": 5000
  },
  "limit": 10,
  "include_evidence": true
}
'@

Invoke-RestMethod `
  -Method Post `
  -Uri "https://api.compassfoodtechnologies.com/v1/search" `
  -Headers $headers `
  -ContentType "application/json" `
  -Body $body

Response

Field	Type	Notes
compass_request_id	string	Request ID for support and logs.
results[]	array	Ranked restaurant results.
results[].address	object	Structured postal address when available and allowed for public response.
results[].coordinates	object	Latitude and longitude when available.
results[].dietary_profile	object	Dietary profile fields such as fully_vegan and vegan_friendly.
results[].cuisine_types	array	Cuisine labels when available.
distance_m	number	Distance from the requested location, present when location is supplied and coordinates are available.
results[].match_for_profile	object	Evidence-aware fit guidance per result when user_profile is included.
metadata	object	Mode, cache, result source, latency, and fetch diagnostics when present.
ai_generated	boolean	Marks generated Compass output.
human_review_recommended	boolean	Signals when review is recommended.

{
  "compass_request_id": "req_abc123",
  "results": [{
    "compass_id": "restaurant_123",
    "name": "Example Ramen",
    "address": {
      "street": "123 Bedford Ave",
      "city": "Brooklyn",
      "state": "NY",
      "postal_code": "11211",
      "country": "US"
    },
    "coordinates": {
      "lat": 40.6782,
      "lng": -73.9442
    },
    "distance_m": 420,
    "vegan_score": {
      "overall": 82,
      "scoring_version": "v3.0-deterministic",
      "dimensions": {
        "D1_vegan_coverage": {
          "score": 90,
          "confidence": "high"
        }
      }
    },
    "dietary_profile": {
      "fully_vegan": false,
      "vegan_friendly": true
    },
    "cuisine_types": ["ramen"],
    "services": {},
    "last_verified_at": "2026-05-11T10:00:00.000Z",
    "last_evaluated_at": "2026-05-11T10:00:00.000Z",
    "evidence": [],
    "match_for_profile": {
      "decision": "unknown",
      "confidence": "low",
      "reason_codes": ["INSUFFICIENT_EVIDENCE"],
      "risk_flags": ["limited_evidence"],
      "verification_required": true,
      "recommended_user_text": "Verify details with the restaurant before visiting."
    }
  }],
  "total_results": 1,
  "ai_generated": true,
  "metadata": {
    "mode": "rich",
    "result_source": "qdrant_restaurants_v2",
    "latency_ms": 1200
  }
}

Decision Safety

Field	Type	Notes
fit	decision	Compass has strong supporting evidence for the submitted profile and no weak, stale, or conflicting evidence signals.
not_fit	decision	Compass has enough structured evidence to reject the submitted profile.
unknown	decision	Compass cannot confirm fit or non-fit with current evidence. Treat this as verify with the restaurant before safety-critical use.
verification_required	boolean	True when the customer should verify details directly with the restaurant before relying on the result.

Modes

Field	Type	Notes
fast	default 5, max 5	Low-latency candidate list with compact score and evidence payload.
rich	default 10, max 50	Fuller evidence, score dimensions, metadata, and per-result fit reasoning.

{
  "compass_request_id": "req_fast123",
  "results": [{
    "compass_id": "restaurant_123",
    "name": "Example Ramen",
    "vegan_score": {
      "overall": 82,
      "scoring_version": "v3.0-deterministic"
    },
    "dietary_profile": {
      "fully_vegan": false,
      "vegan_friendly": true
    }
  }],
  "total_results": 1,
  "ai_generated": true,
  "metadata": {
    "mode": "fast",
    "result_source": "qdrant_restaurants_v2"
  }
}