> ## Documentation Index
> Fetch the complete documentation index at: https://docs.highailabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Dispensary Map

> Interactive map showing nearby dispensaries with filtering by distance, ratings, strain availability, and integration with your wishlist.

<Note>
  **Status:** Planned
  **Tier:** Free (basic map) / Pro (filters, strain availability)
</Note>

## Overview

High IQ already lets you save dispensaries, rate them, and track your visit history. But finding new dispensaries -- or figuring out which nearby location carries a strain you want -- requires leaving the app and searching Google Maps, Weedmaps, or Leafly. That breaks the experience.

The Dispensary Map adds a visual, spatial layer to the dispensary feature. An interactive map shows all nearby dispensaries with real-time location awareness. At the Free tier, it is a clean, fast map with distance and basic info. At the Pro tier, it becomes a strain-aware shopping tool: filter dispensaries by what strains they carry, see which locations stock items on your wishlist, compare ratings and visit history, and plan your next trip without leaving High IQ.

This feature also lays the infrastructure foundation for the Shopping Agent, Neighborhood Ranks, and any future feature that connects strains to physical locations.

## What It Does

* **Interactive map view** -- Full-screen map centered on your current location with dispensary pins showing name, distance, and your personal rating
* **List view toggle** -- Switch between map and list views. List view sorts by distance, rating, or number of visits
* **Dispensary detail cards** -- Tap any pin to see the dispensary name, address, phone, website, your rating, visit count, and notes
* **Distance filtering** -- Filter dispensaries by radius: 5mi, 10mi, 25mi, 50mi
* **Rating filtering** -- Show only dispensaries above a minimum rating threshold
* **Favorites overlay** -- Toggle to show only your favorited dispensaries on the map
* **Strain availability search (Pro)** -- Search for a strain name and see which dispensaries near you carry it, based on available menu data
* **Wishlist matching (Pro)** -- Highlight dispensaries that stock strains from your wishlist. "3 dispensaries within 10 miles carry strains on your wishlist"
* **New dispensary discovery** -- Browse dispensaries beyond your saved list. Discover new locations based on proximity and community ratings
* **Directions integration** -- Tap to open Apple Maps or Google Maps with driving directions to any dispensary
* **Add from map** -- Discover a dispensary on the map and add it to your saved list with one tap

## User Value

<Tip>
  The "aha moment" is searching for a strain you want, seeing which dispensaries near you carry it, and driving directly there with turn-by-turn directions -- all without leaving High IQ. No more cross-referencing three apps to find what you need.
</Tip>

## How It Works

<Steps>
  <Step title="Open Dispensary Map">
    Navigate to the Dispensary Map from the bottom tab bar or the More menu. The map centers on your current location.
  </Step>

  <Step title="Browse Nearby Dispensaries">
    Dispensary pins populate the map within your selected radius. Pins are color-coded: green for your favorites, blue for saved dispensaries, gray for discovered (not yet saved).
  </Step>

  <Step title="Filter and Search">
    Use the filter bar to narrow by distance, minimum rating, or favorites only. Use the search bar to find a specific dispensary by name.
  </Step>

  <Step title="Strain Availability (Pro)">
    Tap the strain search icon and enter a strain name. Dispensary pins that carry that strain are highlighted; others dim. Availability data comes from integrated dispensary menu sources.
  </Step>

  <Step title="View Details">
    Tap any pin to see the dispensary detail card with all saved info plus distance and estimated drive time.
  </Step>

  <Step title="Navigate">
    Tap "Directions" to open Apple Maps or Google Maps with the dispensary address pre-filled.
  </Step>
</Steps>

## Technical Approach

### Map Infrastructure

| Component                       | Technology               | Notes                                                        |
| ------------------------------- | ------------------------ | ------------------------------------------------------------ |
| **Map rendering**               | MapKit (iOS native)      | Apple Maps for iOS. Best performance and native feel on iOS. |
| **Location services**           | Expo Location            | Foreground location permission for current position          |
| **Dispensary data (saved)**     | Convex                   | User's saved dispensaries with ratings, notes, visit history |
| **Dispensary data (discovery)** | External data sources    | Licensed or aggregated dispensary location databases         |
| **Menu/availability data**      | Dispensary platform APIs | Dutchie, Jane, or direct dispensary partnerships             |
| **Geocoding**                   | Apple Geocoding API      | Convert addresses to coordinates for map pins                |
| **Clustering**                  | Custom pin clustering    | Group nearby pins at low zoom levels to prevent clutter      |

### Data Architecture

The map draws from two data sources:

1. **User dispensaries (Convex)** -- The dispensaries you have saved, with your personal ratings, notes, and visit history. These are always shown with full detail.
2. **Discovery dispensaries (API)** -- Dispensaries from external data sources that you have not saved. These appear as dimmed pins with basic info (name, address, distance). Saving one copies it to your Convex data.

### Dispensary Discovery Data

Getting comprehensive dispensary location data is the biggest challenge. Options:

| Source                        | Coverage             | Data Quality                 | Integration Effort           |
| ----------------------------- | -------------------- | ---------------------------- | ---------------------------- |
| **Google Places API**         | High                 | Name, address, hours, photos | Medium (API costs)           |
| **State cannabis registries** | Varies by state      | Official, accurate           | High (per-state integration) |
| **Dutchie/Jane APIs**         | Medium               | Name, address, menu data     | Medium (partnership needed)  |
| **OpenStreetMap**             | Low for dispensaries | Community-maintained         | Low effort, low coverage     |
| **User-contributed**          | Grows over time      | Verified by users            | Built into the app           |

The recommended approach is to start with **Google Places API** for discovery data (broad coverage, reliable) and layer in **Dutchie/Jane menu data** via partnerships for strain availability.

### Strain Availability

The most valuable Pro feature is strain availability search: "Which dispensaries near me have OG Kush?" This requires dispensary menu data, which is available from:

* **Dutchie API** -- Many dispensaries publish menus through Dutchie
* **Jane/iHeartJane** -- Another major dispensary platform
* **Direct partnerships** -- Dispensaries that share their menu data directly
* **Web scraping** -- Some dispensary websites publish menus that can be periodically scraped (with permission)

Menu data is cached with a 24-hour TTL and refreshed in the background. Availability is shown as "likely in stock" rather than guaranteed, with a disclaimer about real-time accuracy.

## Tier Impact

| Tier | Access                                                                                            |
| ---- | ------------------------------------------------------------------------------------------------- |
| Free | Map view, distance filtering, saved dispensaries, directions, basic discovery                     |
| Pro  | Strain availability search, wishlist matching, rating filters, full discovery details, menu links |

## Dependencies

* [x] Dispensary directory with save, rate, and visit tracking -- **built and live**
* [x] Dispensary data in Convex -- **built and live**
* [ ] MapKit integration (iOS native module, requires development build)
* [ ] Expo Location for current position
* [ ] Dispensary discovery data source (Google Places API or equivalent)
* [ ] Geocoding for saved dispensary addresses
* [ ] Pin clustering for map performance
* [ ] Dispensary menu data partnerships (for strain availability)
* [ ] Strain availability search API endpoint
* [ ] Wishlist matching logic

## Open Questions

1. **MapKit vs. react-native-maps?** MapKit gives the best native iOS experience and avoids Google Maps API costs, but `react-native-maps` has a larger community and supports both platforms. Since High IQ is iOS-only, MapKit is the likely choice.
2. **Dispensary discovery data** -- Google Places API charges per request. At scale, this could be expensive. Should we build an internal dispensary database seeded from multiple sources and keep it updated, rather than hitting Google for every map view?
3. **Menu data freshness** -- Dispensary menus change daily. How stale can menu data be before it is misleading? 24-hour cache seems reasonable. Should we show the last-updated timestamp prominently?
4. **Offline map** -- Should the map work offline with cached dispensary pins and saved data? iOS caches map tiles by default, and Convex data syncs locally, so basic offline support may come free.
5. **Privacy of location data** -- Location data is sensitive, especially for cannabis users in stigmatized communities. We should never log precise user locations on our servers. All location processing should happen on-device, with only the dispensary data (not user position) synced to the cloud.

## Related Features

* [Shopping Agent](/planning/features/shopping-agent) -- Uses the map infrastructure to find strains at nearby dispensaries via AI agent
* [Neighborhood Ranks](/planning/features/neighborhood-ranks) -- Regional strain trends displayed on the map
* [Dispensary Tracking](/help/features/dispensaries) -- The existing dispensary directory that the map visualizes
* [Smart Suggestions](/planning/features/smart-suggestions) -- Recommendations gain more value when paired with availability data