# Map Badge Card for Home Assistant

A custom card that shows person locations on a map with profile pictures and activity badges.

![Map Badge Card](https://img.shields.io/badge/Home%20Assistant-Custom%20Card-blue)
![License](https://img.shields.io/badge/license-MIT-green)

![Map Overview](assets/map.png)

## Features

- OpenStreetMap (free) or Google Maps
- Profile pictures as map markers with colored borders based on zones
- Activity badges (walking, driving, etc.) from your phone's sensors
- Customizable colors and border styles
- Adjustable Marker Sizes (Small, Medium, Large)
- Speed Display in Popups
- Speed-based Activity Prediction

### Zone-based Markers

![Home Zone](assets/home.png)

Markers show colored borders based on zones (home = green, away = gray, etc.)

### Google Maps Support

<table>
  <tr>
    <td><img src="assets/gmaps.png" alt="Google Maps" /></td>
    <td><img src="assets/gmaps_45.png" alt="Google Maps 45°" /></td>
  </tr>
  <tr>
    <td align="center">Standard view</td>
    <td align="center">3D tilt at high zoom</td>
  </tr>
</table>

## Installation

### HACS (Recommended)

_Coming soon_

### Manual Installation

1. Download all required files from the `src/` directory:
   - `map-badge-card.js` (main entry point)
   - `constants.js`
   - `config-manager.js`
   - `entity-data-fetcher.js`
   - `iframe-messenger.js`
   - `editor-ui.js`
   - `editor-handlers.js`
   - `map-badge-v2.html`

2. Create a folder `/config/www/map-badge-card/`

3. Copy **all 8 files** into that folder

4. Add the card resource:
   - Go to Settings → Dashboards → Resources
   - Click "Add Resource"
   - URL: `/local/map-badge-card/map-badge-card.js`
   - Resource type: **`JavaScript Module`** (important!)

5. Refresh your browser

**Note:** The card uses ES6 modules, so all files must be in the same directory and the resource type must be set to "JavaScript Module".

## Configuration

### Basic Configuration

```yaml
type: custom:map-badge-card
entities:
  - person: person.john
    activity: sensor.john_phone_activity
  - person: person.jane
    activity: sensor.jane_phone_activity
map_provider: osm  # or 'google'
default_zoom: 13
update_interval: 10  # seconds
```

### Full Configuration Example

```yaml
type: custom:map-badge-card
entities:
  - person: person.john
    activity: sensor.john_phone_activity
  - person: person.jane
    activity: sensor.jane_phone_activity
map_provider: google
google_api_key: YOUR_GOOGLE_API_KEY
map_type: hybrid  # hybrid, satellite, roadmap, or terrain
default_zoom: 15
update_interval: 10
marker_size: medium  # small, medium, large
marker_border_radius: 50%  # 50% for circles, or use px (e.g., 8px)
badge_border_radius: 50%
debug: false
zones:
  home:
    color: '#cef595'
  not_home:
    color: '#757575'
  work:
    color: '#4285f4'
activities:
  still:
    color: '#000000'
  walking:
    color: '#4caf50'
  running:
    color: '#ff5722'
  on_bicycle:
    color: '#2196f3'
  in_vehicle:
    color: '#9c27b0'
activity_source: sensor  # sensor or speed_predicted
```

## Configuration Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `entities` | list | **Required** | List of person entities with optional activity sensors |
| `map_provider` | string | `osm` | Map provider: `osm` (OpenStreetMap) or `google` |
| `google_api_key` | string | - | Google Maps API key (required only for Google Maps) |
| `map_type` | string | `hybrid` | Google Maps type: `hybrid`, `satellite`, `roadmap`, or `terrain` |
| `default_zoom` | number | `13` | Initial map zoom level (1-21) |
| `update_interval` | number | `10` | Update interval in seconds |
| `marker_size` | string | `medium` | Marker size: `small`, `medium`, or `large` |
| `marker_border_radius` | string | `50%` | Border radius for profile pictures |
| `badge_border_radius` | string | `50%` | Border radius for activity badges |
| `debug` | boolean | `false` | Enable debug mode for troubleshooting |
| `zones` | object | See below | Custom zone configurations |
| `activities` | object | See below | Custom activity color configurations |
| `activity_source` | string | `sensor` | Activity source: `sensor` or `speed_predicted` |

### Supported Activities

Based on [Google](https://developers.google.com/android/reference/com/google/android/gms/location/DetectedActivity) and iOS activity detection APIs. Icon colors are customizable.

- Still, On Foot, Walking, Running, Cycling
- In Vehicle (covers car, automotive, etc.)
- On Train, On Bus
- Tilting

All default to black background with white icons.

## Requirements

Your person entities need GPS coordinates (latitude/longitude). Activity sensors come from the [Home Assistant Companion App](https://companion.home-assistant.io/) or similar integrations.

For Google Maps, you'll need an API key from [Google Cloud Console](https://console.cloud.google.com/) with billing enabled. OpenStreetMap works out of the box.

## Notes

### Speed Prediction Feature
The speed-based activity prediction feature requires GPS position history and works best with frequent updates. The card calculates speed based on position changes over time, so:
- Speed display will appear after at least 2 position updates
- Prediction accuracy improves with more frequent GPS updates (e.g., every 10-30 seconds)
- Activity prediction uses the following thresholds:
  - **Still**: < 1 km/h
  - **Walking**: 1-7 km/h 
  - **On Bicycle**: 7-25 km/h
  - **In Vehicle**: > 25 km/h

The speed calculation is performed locally in your browser and uses a Haversine formula for distance calculation between GPS coordinates.