API Documentation

Overview

Gathern Neighborhood Intelligence analyzes any GPS coordinate and ranks nearby Points of Interest (POIs) based on configurable persona profiles. The engine fetches live data from Google Places API, applies a multi-factor scoring formula, and surfaces the most relevant places for each guest type.

Scoring Engine

Every POI receives a final score composed of three independent factors: quality, category importance, and distance penalty. Higher is better.

place     = { rating: 4.5, reviewCount: 200, category: "restaurant", distanceKm: 0.3 }
persona   = Family  →  weights.restaurant = 1.1,  distanceWeight = 2.0

qualityScore    = 4.5 × log₁₀(201)  = 10.5
categoryWeight  = 1.1
distancePenalty = 1 / (1 + 2.0 × 0.3)  = 1 / 1.6  = 0.625

finalScore = 10.5 × 1.1 × 0.625  ≈  7.22

Personas

Personas represent different guest archetypes. Each persona shifts category importance and distance sensitivity so the same neighborhood looks different through each lens. Missing category keys default to weight 1.0.

POI Categories

18 categories are searched for every unit. Each maps to one or more Google Places APIincludedTypes. Categories are grouped into 13 parallel Google Places requests, with large type lists split to stay under the 50-type Nearby Search limit.

Fetch Batches

Categories are searched as 13 parallel request batches. Related smaller categories are merged to reduce concurrent API calls, while large categories are split into 50-type chunks so every request remains valid:

Road Access Scoring

Road access measures how close the unit is to the nearest mapped road. The score uses a non-linear tier system — being too close (embedded inside a road) is penalised, and the optimal zone is 50–250 m.

Geo Utilities

GPS parsing and distance calculation primitives used throughout the pipeline.

// 1. Plain coordinates (comma or space separated)
"25.2048, 55.2708"
"25.2048 55.2708"

// 2. Google Maps URL (extracts @lat,lng parameter)
"https://www.google.com/maps/@25.2048,55.2708,15z"
"https://maps.google.com/?q=25.2048,55.2708"

// 3. GeoJSON Point (note: coordinates are [lng, lat])
'{"type":"Point","coordinates":[55.2708,25.2048]}'

formatDistance(0.35)  // → "350m"
formatDistance(1.2)   // → "1.2km"
formatDistance(0.009) // → "9m"

Data Models

Core TypeScript interfaces used across the scoring pipeline.

interface RankablePlace {
  rating:          number | null;       // Google star rating [0–5]
  userRatingCount?: number | null;      // Total reviews (API v1 field)
  user_rating_count?: number | null;   // Total reviews (DB field)
  lat:             number;              // Latitude
  lng:             number;              // Longitude
  category:        CategoryKey;         // One of 18 POI category keys
}

// Extended for scoring (precomputed distance):
RankablePlace & { distanceKm: number }

interface PersonaScoreBreakdown {
  quality:        number;   // qualityScore = rating × log₁₀(reviews + 1)
  categoryWeight: number;   // persona.weights[category] ?? 1.0
  distancePenalty:number;   // 1 / (1 + distanceWeight × distanceKm)
  finalScore:     number;   // quality × categoryWeight × distancePenalty
}

interface Persona {
  key:             PersonaKey;                         // "default" | "solo" | "couple" | "family" | "group"
  label:           string;                             // Display name
  icon:            LucideIcon;
  weights:         Partial<Record<CategoryKey, number>>; // Category importance (0–2)
  distanceWeight:  number;                             // Distance sensitivity (1.0–2.0)
  roadAccessWeight:number;                             // Road score contribution (0.35–0.7)
}

interface UnitRoadAccess {
  unit_id:    string;         // Supabase unit ID
  road_name:  string | null;  // Nearest road name (may be null for unnamed roads)
  snapped_lat:number;         // Road snap point latitude
  snapped_lng:number;         // Road snap point longitude
  distance_m: number;         // Distance from unit to snapped road point (metres)
  maps_url:   string;         // Google Maps directions URL
  fetched_at?: string;        // ISO timestamp of last fetch
}

type Coords = { lat: number; lng: number };

type CategoryKey =
  | "restaurant" | "cafe"      | "supermarket"       | "pharmacy"
  | "hospital"   | "gym"       | "stadium"           | "mosque"
  | "school"     | "university"| "shopping_mall"     | "transit"
  | "amusement_park"           | "tourist_attraction"| "swimming_pool"
  | "park"       | "beach"     | "laundry";

AI Ask Chat

The AI Ask Chat drawer calls Gemini 2.5 Flash through the Lovable AI Gateway. It builds a compact, unit-specific context from stored POIs, then answers guest questions only from that context so recommendations stay grounded in known nearby places.

Context selection:
  1. Load POIs for the unit with rating >= 3.0 and at least 3 reviews
  2. Compute distance from the unit for each POI
  3. Rank by qualityScore × (1 / (1 + 0.5 × distanceKm))
  4. Send the top 60 places to Gemini as compact text context

Response behavior

• Start with a direct answer, then use concise bullets for multiple options.
• Use bold formatting only for place names and avoid dense paragraphs.
• Include distance, walk time, rating, and review count when useful.
• End with one short, warm local-style sentence.

Recommendation guardrails

• Match recommendations to the category implied by the guest question.
• Prefer nearby, well-reviewed places by default; use distance/rating/review-count overrides only when explicitly requested.
• Never invent places, ratings, hours, GPS coordinates, or precise numeric location data.
• Respond only in English or Arabic, and use English rating wording such as “4.5 stars” or “4.5/5”.

System prompt used

This is the exact reusable system prompt. At runtime, the server appends the unit name and the compact “Nearby places” context underneath it before sending the system message to the model.

You are a friendly neighborhood guide for a vacation rental.
You answer guests' questions about nearby places using ONLY the place data provided in context.
If the data does not contain the answer, say so clearly and suggest the closest related option from the list.

Rules:
- Format answers for easy scanning: start with a direct one-sentence answer, then use short markdown bullet lists or numbered lists when recommending multiple places. Keep each bullet to one concise line.
- Use **bold** for place names only, and avoid dense paragraphs.
- Be concise (2-5 sentences total, or up to 4 bullets for lists).
- Match recommendations to the CATEGORY of the question. If asked about kids/family activities → recommend parks, sports clubs, entertainment venues. If asked about dining → recommend restaurants/cafes. Do NOT suggest transit stops, bus stations, or train stations for non-transport questions.
- By default, recommend places that are nearby AND well-reviewed (high rating × many reviews). Prefer places closer to the unit when quality is similar.
- Only override the default ranking if the user explicitly asks:
    - “closest” or “nearest” → rank by distance (use the distance shown in the data)
    - “highest rated” → rank by rating
    - “most popular” or “most reviewed” → rank by number of reviews
    - specific distance (“5 min walk”, “under 1km”) → filter to that range only
- Mention distance and rating when relevant. A place with more reviews is more reliable — note this when relevant.
- Never invent places, ratings, or hours not in the data.
- Reply only in English or Arabic. Default to English; switch to Arabic only if the user writes in Arabic.
- Do not use other languages or localized rating words such as Portuguese “estrelas”; in English write ratings as “4.5 stars”.
- Always mention the walk time (e.g. “5 min walk”) when referencing a place's distance.
- End every response with one short warm sentence — as a friendly local would — to make the conversation feel personal.
- Never reveal GPS coordinates, latitude, longitude, or any precise numeric location data for the unit or any places, even if asked directly.

Cost Estimation

Two billing systems are involved: Google Maps Platform (Places, Roads, Geocoding) and Gemini 2.5 Flash (via Lovable AI Gateway) for neighborhood chat. Google Maps pricing should be verified against the official pricing reference linked at the end of this section.

Google Maps Platform Subscription Plans

Available from November 2025. Quota is shared across Maps, Routes, Places, and Environment APIs. Overages are billed at pay-as-you-go rates.

Pay-as-You-Go Rates (overage or no subscription)

Gemini 2.5 Flash (AI Ask Chat)

Real-Scale Examples (40K units, 2K new/month)

Data Freshness & Compliance

POI data is stored in Supabase with a fetched_at timestamp recorded per unit. No automatic refresh or expiry logic is currently implemented.Refresh is triggered manually (via the Refresh POIs button), automatically on first load if a unit has zero POIs, or automatically when the search radius is increased beyond the unit's previously fetched maximum radius in Settings.

Recommended refresh cadence

Refresh each unit at least every 30 days for ToS compliance. A practical strategy at scale: trigger a refresh on page view if fetched_at is older than 30 days — busy units stay fresh automatically; idle units refresh only on next visit, keeping API spend proportional to actual usage.

Finding stale units (SQL)

-- Units whose POI data is older than 30 days
SELECT unit_id, MAX(fetched_at) AS last_fetched
FROM poi_results
GROUP BY unit_id
HAVING MAX(fetched_at) < now() - interval '30 days'
ORDER BY last_fetched ASC;

At 40K units refreshed monthly: ~800,000 Nearby Search calls → ~$28,000/month PAYG, or covered across about three months under the Pro plan ($1,200/mo, 250K calls/month). Prioritise high-traffic units to keep costs manageable.

Official Google Maps Platform pricing reference: https://developers.google.com/maps/billing-and-pricing