map-locations

Name	map-locations JSON
Version	0.2.1 JSON
	download
home_page	https://github.com/shpigi/map-locations
Summary	A Python library for mapping locations with interactive filtering and visualization capabilities
upload_time	2025-07-20 03:56:35
maintainer	None
docs_url	None
author	Lavi Shpigelman
requires_python	>=3.10
license	MIT
keywords	maps locations folium yaml geojson kml gis geospatial data-visualization ai-friendly type-hints data-analysis
VCS
bugtrack_url
requirements	folium pyyaml
Travis-CI	No Travis.
coveralls test coverage	No coveralls.

            # Map Locations

A Python library and CLI tool for mapping locations with interactive filtering and visualization capabilities.

[![CI](https://github.com/shpigi/map-locations/workflows/CI/badge.svg)](https://github.com/shpigi/map-locations/actions)
[![Codecov](https://codecov.io/gh/shpigi/map-locations/branch/main/graph/badge.svg)](https://codecov.io/gh/shpigi/map-locations)

**Author:** Lavi Shpigelman

## Features

- 📍 **Interactive Maps**: Create beautiful, interactive maps using Folium
- 🗺️ **Multiple Tile Providers**: Support for OpenStreetMap, Google Maps, and Google Satellite
- 🏷️ **Tag-based Filtering**: Filter locations by tags and types
- 🎨 **Color-coded Types**: Different location types are displayed with distinct colors
- 📝 **Toggle Labels**: Show/hide location names on the map
- 📊 **Multiple Export Formats**: Export to KML, GeoJSON, and HTML
- 📁 **YAML Configuration**: Simple YAML format for location data
- 🖥️ **CLI Interface**: Command-line tool for easy map generation

## Installation

### From PyPI (when published)

```bash
pip install map-locations
```

### From Source

```bash
# Clone the repository
git clone https://github.com/shpigi/map-locations.git
cd map-locations

# Install in development mode
pip install -e .

# Or install with development dependencies
pip install -e ".[dev]"
```

### Development Setup

```bash
# Install with all development tools
make install-dev

# Set up pre-commit hooks
make setup-dev
```

## Quick Start

### 1. Create a locations file

Create a YAML file with your locations:

```yaml
locations:
  - name: "Galerie Vivienne"
    type: "passage"
    latitude: 48.8667
    longitude: 2.3397
    tags: ["historic"]
    neighborhood: "2nd arrondissement"
    date_added: "2025-07-19"
    date_of_visit: "YYYY-MM-DD"

  - name: "Passage des Panoramas"
    type: "passage"
    latitude: 48.87111
    longitude: 2.34167
    tags: ["historic"]
    neighborhood: "2nd arrondissement"
    date_added: "2025-07-19"
    date_of_visit: "YYYY-MM-DD"
```

### 2. Generate a map

```bash
# Using the CLI tool
map-locations locations.yaml --output map.html

# Or using Python
python -c "
from map_locations import load_locations_from_yaml, show_locations_grouped
locations = load_locations_from_yaml('locations.yaml')
show_locations_grouped(locations, map_filename='map.html')
"
```

### 3. Export to different formats

```bash
# Export to all formats (JSON, CSV, GeoJSON, KML, HTML)
map-locations locations.yaml --format all --output exports/locations

# Export to specific format
map-locations locations.yaml --format json --output exports/locations.json
map-locations locations.yaml --format csv --output exports/locations.csv
map-locations locations.yaml --format geojson --output exports/locations.geojson
map-locations locations.yaml --format kml --output exports/locations.kml
map-locations locations.yaml --format html --output exports/locations.html
```

### 4. Import into Google My Maps

You can easily import your exported KML files into [Google My Maps](https://www.google.com/maps/d/u/0/) for additional features. See the [Google My Maps Integration](#google-my-maps-integration) section below for detailed instructions.

## For AI Agents

This package is designed to be AI-agent friendly with comprehensive type hints, clear function signatures, and utility functions for common operations.

### Core Data Structure

```python
from map_locations import Location

# Location is a TypedDict with the following structure:
Location = {
    "name": str,           # Required: Location name
    "type": str,           # Required: Location type/category
    "latitude": float,      # Required: Latitude coordinate
    "longitude": float,     # Required: Longitude coordinate
    "tags": List[str],      # Optional: List of tags for filtering
    "neighborhood": str,    # Optional: Neighborhood or area name
    "date_added": str,      # Optional: Date when added (YYYY-MM-DD)
    "date_of_visit": str,   # Optional: Date of visit (YYYY-MM-DD)
}
```

### Quick AI Agent Usage Examples

```python
from map_locations import (
    load_locations_from_yaml,
    create_sample_locations,
    get_location_summary,
    filter_locations_by_type,
    validate_location_data,
    show_locations_grouped,
    export_to_all_formats,
)

# Load existing data or create sample data
locations = load_locations_from_yaml("my_locations.yaml")
# OR
locations = create_sample_locations()

# Get summary of available data
summary = get_location_summary(locations)
print(f"Total locations: {summary['total_count']}")
print(f"Available types: {summary['types']}")
print(f"Available tags: {summary['tags']}")

# Validate data for issues
issues = validate_location_data(locations)
if issues['missing_required']:
    print(f"Data issues found: {issues}")

# Filter and visualize
restaurants = filter_locations_by_type(locations, ["restaurant", "cafe"])
show_locations_grouped(restaurants, "restaurants_map.html")

# Export to multiple formats
export_to_all_formats(locations, "exports/my_locations")
```

### Available Functions for AI Agents

#### Data Loading and Validation
- `load_locations_from_yaml(yaml_path: str) -> List[Location]`
- `create_sample_locations() -> List[Location]`
- `validate_location_data(locations: List[Location]) -> Dict[str, List[str]]`

#### Data Analysis
- `get_location_summary(locations: List[Location]) -> Dict[str, Any]`
- `get_available_types(locations: List[Location]) -> List[str]`
- `get_available_tags(locations: List[Location]) -> List[str]`
- `get_available_neighborhoods(locations: List[Location]) -> List[str]`

#### Filtering
- `filter_locations_by_type(locations: List[Location], types: List[str]) -> List[Location]`
- `filter_locations_by_tags(locations: List[Location], tags: List[str]) -> List[Location]`
- `filter_locations_by_neighborhood(locations: List[Location], neighborhoods: List[str]) -> List[Location]`

#### Visualization
- `show_locations_grouped(locations: List[Location], group_by: str = "type", map_filename: str = "map.html")`
- `show_locations_with_filtering(locations: List[Location], map_filename: str = "map.html")`
- `show_locations_with_google_maps(locations: List[Location], map_filename: str = "map.html")`

#### Export
- `export_to_json(locations: List[Location], output_path: str)`
- `export_to_csv(locations: List[Location], output_path: str)`
- `export_to_geojson(locations: List[Location], output_path: str)`
- `export_to_kml(locations: List[Location], output_path: str)`
- `export_to_all_formats(locations: List[Location], base_path: str)`

### Common AI Agent Workflows

#### 1. Data Exploration
```python
from map_locations import load_locations_from_yaml, get_location_summary

locations = load_locations_from_yaml("data.yaml")
summary = get_location_summary(locations)
print(f"Dataset contains {summary['total_count']} locations")
print(f"Types: {summary['types']}")
print(f"Top types: {dict(sorted(summary['type_counts'].items(), key=lambda x: x[1], reverse=True)[:5])}")
```

#### 2. Data Validation
```python
from map_locations import validate_location_data

issues = validate_location_data(locations)
if any(issues.values()):
    print("Data validation issues found:")
    for category, problems in issues.items():
        if problems:
            print(f"  {category}: {problems}")
else:
    print("✅ Data validation passed")
```

#### 3. Filtered Analysis
```python
from map_locations import filter_locations_by_type, filter_locations_by_tags

# Get all food-related locations
food_locations = filter_locations_by_type(locations, ["restaurant", "cafe", "bar"])

# Get all historic sites
historic_sites = filter_locations_by_tags(locations, ["historic"])

# Create maps for each category
show_locations_grouped(food_locations, "food_map.html")
show_locations_grouped(historic_sites, "historic_map.html")
```

#### 4. Complete Workflow
```python
from map_locations import (
    load_locations_from_yaml,
    validate_location_data,
    get_location_summary,
    filter_locations_by_type,
    show_locations_grouped,
    export_to_all_formats,
)

# Load and validate
locations = load_locations_from_yaml("locations.yaml")
issues = validate_location_data(locations)
if issues['missing_required']:
    print("❌ Data has issues, please fix before proceeding")
    exit(1)

# Analyze
summary = get_location_summary(locations)
print(f"✅ Loaded {summary['total_count']} valid locations")

# Filter and visualize
museums = filter_locations_by_type(locations, ["museum", "gallery"])
show_locations_grouped(museums, "museums_map.html")

# Export
export_to_all_formats(locations, "exports/complete_dataset")
print("✅ All exports completed")
```

## Tile Providers

The library supports multiple tile providers for different map styles:

### OpenStreetMap (Default)
- **Cost**: Free
- **Usage**: No API key required
- **Best for**: General use, open data

### Google Maps
- **Cost**: Free for personal use, requires API key for commercial use
- **Usage**: No API key required for personal use
- **Best for**: Familiar interface, detailed street data

### Google Satellite
- **Cost**: Free for personal use, requires API key for commercial use
- **Usage**: No API key required for personal use
- **Best for**: Aerial views, terrain analysis

**Note**: Google Maps tiles are free for personal use but may require an API key and payment for commercial use or high-volume usage. For commercial applications, consider using the official Google Maps JavaScript API.

## Location Data Format

Each location in your YAML file should include:

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | ✅ | Location name |
| `type` | string | ✅ | Location type (determines color) |
| `latitude` | float | ✅ | Latitude coordinate |
| `longitude` | float | ✅ | Longitude coordinate |
| `tags` | list | ❌ | Array of tags for filtering |
| `neighborhood` | string | ❌ | Neighborhood or area |
| `date_added` | string | ❌ | Date added to collection |
| `date_of_visit` | string | ❌ | date of visit (use "YYYY-MM-DD") |

### Example Location Entry

```yaml
- name: "Passage du Grand Cerf"
  type: "passage"
  latitude: 48.86483
  longitude: 2.34933
  tags: ["architecture", "glass roof"]
  neighborhood: "2nd arrondissement"
  date_added: "2025-07-19"
  date_of_visit: "YYYY-MM-DD"
```

## CLI Usage

The CLI supports multiple formats with a single command structure:

### Available Formats

- `html` - Interactive HTML map (default)
- `json` - JSON format
- `csv` - CSV format
- `geojson` - GeoJSON format
- `kml` - KML format with grouped folders for Google Maps
- `all` - All formats including HTML

### Basic Usage

```bash
# Create HTML map (default)
map-locations locations.yaml --output map.html

# Export to specific format
map-locations locations.yaml --format json --output locations.json
map-locations locations.yaml --format kml --output locations.kml

# Export to all formats (including HTML)
map-locations locations.yaml --format all --output locations
```

### Advanced Options

```bash
# Create map with Google Maps tiles
map-locations locations.yaml --tile-provider google_maps --output map.html

# Create map with Google Satellite view
map-locations locations.yaml --tile-provider google_satellite --output map.html

# Group by different fields
map-locations locations.yaml --group-by neighborhood --output map.html
map-locations locations.yaml --group-by date_added --output map.html
```

**See also**: [Grouping Options](#grouping-options) and [Tile Provider Options](#tile-provider-options) for more examples.

**Note**: For importing into Google My Maps, use the KML format. See [Google My Maps Integration](#google-my-maps-integration) for details.

### Google My Maps Integration

Export your locations to KML format and import them into [Google My Maps](https://www.google.com/maps/d/u/0/) for enhanced features:

```bash
# Export to KML for Google My Maps
map-locations locations.yaml --format kml --output my_locations.kml
```

**Steps to import into Google My Maps**:
1. Go to [Google My Maps](https://www.google.com/maps/d/u/0/)
2. Click "Create a new map"
3. Click "Import" in the left panel
4. Upload your KML file
5. Your locations will appear with all details preserved

**Google My Maps Features**:
- 📱 **Mobile Access**: View maps on smartphones and tablets
- 👥 **Sharing**: Share maps via link or email
- 🎨 **Custom Styling**: Change colors, icons, and labels
- 📝 **Collaboration**: Allow others to edit your maps
- 🗺️ **Offline Access**: Download maps for offline use
- 📍 **Custom Markers**: Add custom icons and descriptions
- 🗂️ **Layers**: Organize locations into different layers

### Grouping Options

```bash
# Group by neighborhood (default)
map-locations locations.yaml --group-by neighborhood

# Group by location type
map-locations locations.yaml --group-by type

# Group by date added
map-locations locations.yaml --group-by date_added

# Group by date of visit
map-locations locations.yaml --group-by date_of_visit
```

### Tile Provider Options

```bash
# Use OpenStreetMap (default, free)
map-locations locations.yaml --tile-provider openstreetmap

# Use Google Maps (free for personal use)
map-locations locations.yaml --tile-provider google_maps

# Use Google Satellite (free for personal use)
map-locations locations.yaml --tile-provider google_satellite
```

## Library Usage

### Basic Map Generation

```python
from map_locations import load_locations_from_yaml, show_locations_grouped

# Load locations from YAML
locations = load_locations_from_yaml("locations.yaml")

# Generate interactive map with grouping (defaults to type)
show_locations_grouped(locations, group_by="type", map_filename="map.html")

# Generate map with Google Maps tiles
show_locations_grouped(
    locations,
    group_by="type",
    map_filename="map.html",
    tile_provider="google_maps"
)

# Generate map with Google Satellite view
show_locations_grouped(
    locations,
    group_by="type",
    map_filename="map.html",
    tile_provider="google_satellite"
)
```

### Grouping and Organization

```python
from map_locations import load_locations_from_yaml, show_locations_grouped

locations = load_locations_from_yaml("locations.yaml")

# Group by type (default)
show_locations_grouped(locations, group_by="type", map_filename="type_map.html")

# Group by neighborhood
show_locations_grouped(locations, group_by="neighborhood", map_filename="neighborhood_map.html")

# Group by date added
show_locations_grouped(locations, group_by="date_added", map_filename="date_map.html")
```

**See also**: [Grouping Options](#grouping-options) for CLI examples of all available grouping fields.

### Data Loading

```python
from map_locations import load_locations_from_yaml

# Load locations from YAML file
locations = load_locations_from_yaml("locations.yaml")

# Access location data
for location in locations:
    print(f"Name: {location['name']}")
    print(f"Type: {location.get('type', 'Unknown')}")
    print(f"Tags: {location.get('tags', [])}")
    print(f"Coordinates: {location['latitude']}, {location['longitude']}")
```

## Development

### Setup Development Environment

```bash
# Clone the repository
git clone https://github.com/shpigi/map-locations.git
cd map-locations

# Install with development dependencies
make install-dev

# Set up pre-commit hooks
make setup-dev
```

**Note**: This setup is also covered in the [Installation](#installation) section above.

### Running Tests

```bash
# Run all tests
make test

# Run tests with coverage
pytest tests/ -v --cov=map_locations --cov-report=html

# Run specific test file
pytest tests/test_core.py -v
```

### Code Quality

```bash
# Format code
make format

# Run linting (pre-commit checks on all files)
make lint

# Run linting on staged files only
make lint-staged
```

### Pre-commit Hooks

This project uses pre-commit hooks to ensure code quality. The hooks will automatically run on every commit and include:

- **Code Formatting**: Black for code formatting, isort for import sorting
- **Linting**: Flake8 for style checking, MyPy for type checking
- **File Checks**: YAML validation, JSON validation, trailing whitespace removal
- **Security**: Private key detection, merge conflict detection

#### Setting up pre-commit hooks:

```bash
# Install pre-commit hooks (automatically done with setup-dev)
make setup-dev

# Or manually:
pre-commit install
```

#### Running pre-commit checks manually:

```bash
# Run all hooks on all files
pre-commit run --all-files

# Run specific hook
pre-commit run black

# Run hooks on staged files only
pre-commit run
```



#### Code Style Standards

This project follows strict code quality standards:

- **Line Length**: Maximum 100 characters
- **Formatting**: Black for code formatting, isort for imports
- **Linting**: Flake8 for style checking
- **Type Checking**: MyPy for type validation
- **Documentation**: Google-style docstrings

The pre-commit hooks will automatically enforce these standards.

### Building and Publishing

```bash
# Build the package
make build

# Clean build artifacts
make clean

# Publish to PyPI (requires proper configuration)
make publish
```

### Running Examples

```bash
# Run the basic usage example
python examples/basic_usage.py

# Test the CLI
make test-cli
```

## Map Features

### Interactive Elements

- **Clickable Markers**: Click on any location to see detailed popup with name, type, tags, and dates
- **Zoom Controls**: Zoom in/out with mouse wheel or controls
- **Pan Navigation**: Click and drag to move around the map
- **Fullscreen Mode**: Toggle fullscreen view
- **Layer Control**: Toggle visibility of different groups with the layer control panel

### Color Coding

Different groups are automatically assigned colors from a predefined color palette:

- **Group Colors**: Each group (neighborhood, type, etc.) gets a unique color
- **Color Palette**: Red, blue, green, purple, orange, darkred, lightred, beige, darkblue, darkgreen, cadetblue
- **Automatic Cycling**: Colors cycle through the palette for multiple groups
- **Fallback**: Gray color for additional groups beyond the palette

### Popup Information

- **Detailed Popups**: Click any marker to see comprehensive information including:
  - Location name
  - Type
  - Tags
  - Date added
  - date of visit
- **Tooltips**: Hover over markers to see location names
- **Layer Control**: Toggle visibility of different groups using the layer control panel

## Configuration

### Grouping Options

The `show_locations_grouped` function allows you to group locations by any field in your YAML:

```python
from map_locations import load_locations_from_yaml, show_locations_grouped

locations = load_locations_from_yaml("locations.yaml")

# Group by any field
show_locations_grouped(locations, group_by="type")          # By type (default)
show_locations_grouped(locations, group_by="neighborhood")  # By area
show_locations_grouped(locations, group_by="date_added")    # By date
show_locations_grouped(locations, group_by="tags")          # By tags
```

### Map Styling

```python
from map_locations import load_locations_from_yaml, show_locations_grouped

locations = load_locations_from_yaml("locations.yaml")

# Custom map options
show_locations_grouped(
    locations,
    group_by="type",
    map_filename="custom_map.html"
)
```

**See also**: [Tile Providers](#tile-providers) for available tile provider options and [Tile Provider Options](#tile-provider-options) for CLI examples.

## Examples

### Paris Passages Map

The included example shows historic passages in Paris:

```bash
# Generate the Paris passages map grouped by type (default)
map-locations generate --input map_locations/maps/passages/locations.yaml --group-by type --output passages_map.html
```

This creates an interactive map of Paris's historic covered passages with:
- Locations grouped by type (default)
- Color-coded groups with layer controls
- Detailed popups showing name, type, tags, and dates
- Interactive layer panel to toggle group visibility

## Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Acknowledgments

- Built with [Folium](https://python-visualization.github.io/folium/) for interactive maps
- Uses [SimpleKML](https://simplekml.readthedocs.io/) for KML export
- Inspired by the historic passages of Paris

            

Raw data

            {
    "_id": null,
    "home_page": "https://github.com/shpigi/map-locations",
    "name": "map-locations",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.10",
    "maintainer_email": "Lavi Shpigelman <lavi.shpigelman@gmail.com>",
    "keywords": "maps, locations, folium, yaml, geojson, kml, gis, geospatial, data-visualization, ai-friendly, type-hints, data-analysis",
    "author": "Lavi Shpigelman",
    "author_email": "Lavi Shpigelman <lavi.shpigelman@gmail.com>",
    "download_url": "https://files.pythonhosted.org/packages/f3/45/2256f04fec2712faf18bc89929d9b0048c8e429c7aeadb8e0f3da8265ede/map_locations-0.2.1.tar.gz",
    "platform": null,
    "description": "# Map Locations\n\nA Python library and CLI tool for mapping locations with interactive filtering and visualization capabilities.\n\n[![CI](https://github.com/shpigi/map-locations/workflows/CI/badge.svg)](https://github.com/shpigi/map-locations/actions)\n[![Codecov](https://codecov.io/gh/shpigi/map-locations/branch/main/graph/badge.svg)](https://codecov.io/gh/shpigi/map-locations)\n\n**Author:** Lavi Shpigelman\n\n## Features\n\n- \ud83d\udccd **Interactive Maps**: Create beautiful, interactive maps using Folium\n- \ud83d\uddfa\ufe0f **Multiple Tile Providers**: Support for OpenStreetMap, Google Maps, and Google Satellite\n- \ud83c\udff7\ufe0f **Tag-based Filtering**: Filter locations by tags and types\n- \ud83c\udfa8 **Color-coded Types**: Different location types are displayed with distinct colors\n- \ud83d\udcdd **Toggle Labels**: Show/hide location names on the map\n- \ud83d\udcca **Multiple Export Formats**: Export to KML, GeoJSON, and HTML\n- \ud83d\udcc1 **YAML Configuration**: Simple YAML format for location data\n- \ud83d\udda5\ufe0f **CLI Interface**: Command-line tool for easy map generation\n\n## Installation\n\n### From PyPI (when published)\n\n```bash\npip install map-locations\n```\n\n### From Source\n\n```bash\n# Clone the repository\ngit clone https://github.com/shpigi/map-locations.git\ncd map-locations\n\n# Install in development mode\npip install -e .\n\n# Or install with development dependencies\npip install -e \".[dev]\"\n```\n\n### Development Setup\n\n```bash\n# Install with all development tools\nmake install-dev\n\n# Set up pre-commit hooks\nmake setup-dev\n```\n\n## Quick Start\n\n### 1. Create a locations file\n\nCreate a YAML file with your locations:\n\n```yaml\nlocations:\n  - name: \"Galerie Vivienne\"\n    type: \"passage\"\n    latitude: 48.8667\n    longitude: 2.3397\n    tags: [\"historic\"]\n    neighborhood: \"2nd arrondissement\"\n    date_added: \"2025-07-19\"\n    date_of_visit: \"YYYY-MM-DD\"\n\n  - name: \"Passage des Panoramas\"\n    type: \"passage\"\n    latitude: 48.87111\n    longitude: 2.34167\n    tags: [\"historic\"]\n    neighborhood: \"2nd arrondissement\"\n    date_added: \"2025-07-19\"\n    date_of_visit: \"YYYY-MM-DD\"\n```\n\n### 2. Generate a map\n\n```bash\n# Using the CLI tool\nmap-locations locations.yaml --output map.html\n\n# Or using Python\npython -c \"\nfrom map_locations import load_locations_from_yaml, show_locations_grouped\nlocations = load_locations_from_yaml('locations.yaml')\nshow_locations_grouped(locations, map_filename='map.html')\n\"\n```\n\n### 3. Export to different formats\n\n```bash\n# Export to all formats (JSON, CSV, GeoJSON, KML, HTML)\nmap-locations locations.yaml --format all --output exports/locations\n\n# Export to specific format\nmap-locations locations.yaml --format json --output exports/locations.json\nmap-locations locations.yaml --format csv --output exports/locations.csv\nmap-locations locations.yaml --format geojson --output exports/locations.geojson\nmap-locations locations.yaml --format kml --output exports/locations.kml\nmap-locations locations.yaml --format html --output exports/locations.html\n```\n\n### 4. Import into Google My Maps\n\nYou can easily import your exported KML files into [Google My Maps](https://www.google.com/maps/d/u/0/) for additional features. See the [Google My Maps Integration](#google-my-maps-integration) section below for detailed instructions.\n\n## For AI Agents\n\nThis package is designed to be AI-agent friendly with comprehensive type hints, clear function signatures, and utility functions for common operations.\n\n### Core Data Structure\n\n```python\nfrom map_locations import Location\n\n# Location is a TypedDict with the following structure:\nLocation = {\n    \"name\": str,           # Required: Location name\n    \"type\": str,           # Required: Location type/category\n    \"latitude\": float,      # Required: Latitude coordinate\n    \"longitude\": float,     # Required: Longitude coordinate\n    \"tags\": List[str],      # Optional: List of tags for filtering\n    \"neighborhood\": str,    # Optional: Neighborhood or area name\n    \"date_added\": str,      # Optional: Date when added (YYYY-MM-DD)\n    \"date_of_visit\": str,   # Optional: Date of visit (YYYY-MM-DD)\n}\n```\n\n### Quick AI Agent Usage Examples\n\n```python\nfrom map_locations import (\n    load_locations_from_yaml,\n    create_sample_locations,\n    get_location_summary,\n    filter_locations_by_type,\n    validate_location_data,\n    show_locations_grouped,\n    export_to_all_formats,\n)\n\n# Load existing data or create sample data\nlocations = load_locations_from_yaml(\"my_locations.yaml\")\n# OR\nlocations = create_sample_locations()\n\n# Get summary of available data\nsummary = get_location_summary(locations)\nprint(f\"Total locations: {summary['total_count']}\")\nprint(f\"Available types: {summary['types']}\")\nprint(f\"Available tags: {summary['tags']}\")\n\n# Validate data for issues\nissues = validate_location_data(locations)\nif issues['missing_required']:\n    print(f\"Data issues found: {issues}\")\n\n# Filter and visualize\nrestaurants = filter_locations_by_type(locations, [\"restaurant\", \"cafe\"])\nshow_locations_grouped(restaurants, \"restaurants_map.html\")\n\n# Export to multiple formats\nexport_to_all_formats(locations, \"exports/my_locations\")\n```\n\n### Available Functions for AI Agents\n\n#### Data Loading and Validation\n- `load_locations_from_yaml(yaml_path: str) -> List[Location]`\n- `create_sample_locations() -> List[Location]`\n- `validate_location_data(locations: List[Location]) -> Dict[str, List[str]]`\n\n#### Data Analysis\n- `get_location_summary(locations: List[Location]) -> Dict[str, Any]`\n- `get_available_types(locations: List[Location]) -> List[str]`\n- `get_available_tags(locations: List[Location]) -> List[str]`\n- `get_available_neighborhoods(locations: List[Location]) -> List[str]`\n\n#### Filtering\n- `filter_locations_by_type(locations: List[Location], types: List[str]) -> List[Location]`\n- `filter_locations_by_tags(locations: List[Location], tags: List[str]) -> List[Location]`\n- `filter_locations_by_neighborhood(locations: List[Location], neighborhoods: List[str]) -> List[Location]`\n\n#### Visualization\n- `show_locations_grouped(locations: List[Location], group_by: str = \"type\", map_filename: str = \"map.html\")`\n- `show_locations_with_filtering(locations: List[Location], map_filename: str = \"map.html\")`\n- `show_locations_with_google_maps(locations: List[Location], map_filename: str = \"map.html\")`\n\n#### Export\n- `export_to_json(locations: List[Location], output_path: str)`\n- `export_to_csv(locations: List[Location], output_path: str)`\n- `export_to_geojson(locations: List[Location], output_path: str)`\n- `export_to_kml(locations: List[Location], output_path: str)`\n- `export_to_all_formats(locations: List[Location], base_path: str)`\n\n### Common AI Agent Workflows\n\n#### 1. Data Exploration\n```python\nfrom map_locations import load_locations_from_yaml, get_location_summary\n\nlocations = load_locations_from_yaml(\"data.yaml\")\nsummary = get_location_summary(locations)\nprint(f\"Dataset contains {summary['total_count']} locations\")\nprint(f\"Types: {summary['types']}\")\nprint(f\"Top types: {dict(sorted(summary['type_counts'].items(), key=lambda x: x[1], reverse=True)[:5])}\")\n```\n\n#### 2. Data Validation\n```python\nfrom map_locations import validate_location_data\n\nissues = validate_location_data(locations)\nif any(issues.values()):\n    print(\"Data validation issues found:\")\n    for category, problems in issues.items():\n        if problems:\n            print(f\"  {category}: {problems}\")\nelse:\n    print(\"\u2705 Data validation passed\")\n```\n\n#### 3. Filtered Analysis\n```python\nfrom map_locations import filter_locations_by_type, filter_locations_by_tags\n\n# Get all food-related locations\nfood_locations = filter_locations_by_type(locations, [\"restaurant\", \"cafe\", \"bar\"])\n\n# Get all historic sites\nhistoric_sites = filter_locations_by_tags(locations, [\"historic\"])\n\n# Create maps for each category\nshow_locations_grouped(food_locations, \"food_map.html\")\nshow_locations_grouped(historic_sites, \"historic_map.html\")\n```\n\n#### 4. Complete Workflow\n```python\nfrom map_locations import (\n    load_locations_from_yaml,\n    validate_location_data,\n    get_location_summary,\n    filter_locations_by_type,\n    show_locations_grouped,\n    export_to_all_formats,\n)\n\n# Load and validate\nlocations = load_locations_from_yaml(\"locations.yaml\")\nissues = validate_location_data(locations)\nif issues['missing_required']:\n    print(\"\u274c Data has issues, please fix before proceeding\")\n    exit(1)\n\n# Analyze\nsummary = get_location_summary(locations)\nprint(f\"\u2705 Loaded {summary['total_count']} valid locations\")\n\n# Filter and visualize\nmuseums = filter_locations_by_type(locations, [\"museum\", \"gallery\"])\nshow_locations_grouped(museums, \"museums_map.html\")\n\n# Export\nexport_to_all_formats(locations, \"exports/complete_dataset\")\nprint(\"\u2705 All exports completed\")\n```\n\n## Tile Providers\n\nThe library supports multiple tile providers for different map styles:\n\n### OpenStreetMap (Default)\n- **Cost**: Free\n- **Usage**: No API key required\n- **Best for**: General use, open data\n\n### Google Maps\n- **Cost**: Free for personal use, requires API key for commercial use\n- **Usage**: No API key required for personal use\n- **Best for**: Familiar interface, detailed street data\n\n### Google Satellite\n- **Cost**: Free for personal use, requires API key for commercial use\n- **Usage**: No API key required for personal use\n- **Best for**: Aerial views, terrain analysis\n\n**Note**: Google Maps tiles are free for personal use but may require an API key and payment for commercial use or high-volume usage. For commercial applications, consider using the official Google Maps JavaScript API.\n\n## Location Data Format\n\nEach location in your YAML file should include:\n\n| Field | Type | Required | Description |\n|-------|------|----------|-------------|\n| `name` | string | \u2705 | Location name |\n| `type` | string | \u2705 | Location type (determines color) |\n| `latitude` | float | \u2705 | Latitude coordinate |\n| `longitude` | float | \u2705 | Longitude coordinate |\n| `tags` | list | \u274c | Array of tags for filtering |\n| `neighborhood` | string | \u274c | Neighborhood or area |\n| `date_added` | string | \u274c | Date added to collection |\n| `date_of_visit` | string | \u274c | date of visit (use \"YYYY-MM-DD\") |\n\n### Example Location Entry\n\n```yaml\n- name: \"Passage du Grand Cerf\"\n  type: \"passage\"\n  latitude: 48.86483\n  longitude: 2.34933\n  tags: [\"architecture\", \"glass roof\"]\n  neighborhood: \"2nd arrondissement\"\n  date_added: \"2025-07-19\"\n  date_of_visit: \"YYYY-MM-DD\"\n```\n\n## CLI Usage\n\nThe CLI supports multiple formats with a single command structure:\n\n### Available Formats\n\n- `html` - Interactive HTML map (default)\n- `json` - JSON format\n- `csv` - CSV format\n- `geojson` - GeoJSON format\n- `kml` - KML format with grouped folders for Google Maps\n- `all` - All formats including HTML\n\n### Basic Usage\n\n```bash\n# Create HTML map (default)\nmap-locations locations.yaml --output map.html\n\n# Export to specific format\nmap-locations locations.yaml --format json --output locations.json\nmap-locations locations.yaml --format kml --output locations.kml\n\n# Export to all formats (including HTML)\nmap-locations locations.yaml --format all --output locations\n```\n\n### Advanced Options\n\n```bash\n# Create map with Google Maps tiles\nmap-locations locations.yaml --tile-provider google_maps --output map.html\n\n# Create map with Google Satellite view\nmap-locations locations.yaml --tile-provider google_satellite --output map.html\n\n# Group by different fields\nmap-locations locations.yaml --group-by neighborhood --output map.html\nmap-locations locations.yaml --group-by date_added --output map.html\n```\n\n**See also**: [Grouping Options](#grouping-options) and [Tile Provider Options](#tile-provider-options) for more examples.\n\n**Note**: For importing into Google My Maps, use the KML format. See [Google My Maps Integration](#google-my-maps-integration) for details.\n\n### Google My Maps Integration\n\nExport your locations to KML format and import them into [Google My Maps](https://www.google.com/maps/d/u/0/) for enhanced features:\n\n```bash\n# Export to KML for Google My Maps\nmap-locations locations.yaml --format kml --output my_locations.kml\n```\n\n**Steps to import into Google My Maps**:\n1. Go to [Google My Maps](https://www.google.com/maps/d/u/0/)\n2. Click \"Create a new map\"\n3. Click \"Import\" in the left panel\n4. Upload your KML file\n5. Your locations will appear with all details preserved\n\n**Google My Maps Features**:\n- \ud83d\udcf1 **Mobile Access**: View maps on smartphones and tablets\n- \ud83d\udc65 **Sharing**: Share maps via link or email\n- \ud83c\udfa8 **Custom Styling**: Change colors, icons, and labels\n- \ud83d\udcdd **Collaboration**: Allow others to edit your maps\n- \ud83d\uddfa\ufe0f **Offline Access**: Download maps for offline use\n- \ud83d\udccd **Custom Markers**: Add custom icons and descriptions\n- \ud83d\uddc2\ufe0f **Layers**: Organize locations into different layers\n\n### Grouping Options\n\n```bash\n# Group by neighborhood (default)\nmap-locations locations.yaml --group-by neighborhood\n\n# Group by location type\nmap-locations locations.yaml --group-by type\n\n# Group by date added\nmap-locations locations.yaml --group-by date_added\n\n# Group by date of visit\nmap-locations locations.yaml --group-by date_of_visit\n```\n\n### Tile Provider Options\n\n```bash\n# Use OpenStreetMap (default, free)\nmap-locations locations.yaml --tile-provider openstreetmap\n\n# Use Google Maps (free for personal use)\nmap-locations locations.yaml --tile-provider google_maps\n\n# Use Google Satellite (free for personal use)\nmap-locations locations.yaml --tile-provider google_satellite\n```\n\n## Library Usage\n\n### Basic Map Generation\n\n```python\nfrom map_locations import load_locations_from_yaml, show_locations_grouped\n\n# Load locations from YAML\nlocations = load_locations_from_yaml(\"locations.yaml\")\n\n# Generate interactive map with grouping (defaults to type)\nshow_locations_grouped(locations, group_by=\"type\", map_filename=\"map.html\")\n\n# Generate map with Google Maps tiles\nshow_locations_grouped(\n    locations,\n    group_by=\"type\",\n    map_filename=\"map.html\",\n    tile_provider=\"google_maps\"\n)\n\n# Generate map with Google Satellite view\nshow_locations_grouped(\n    locations,\n    group_by=\"type\",\n    map_filename=\"map.html\",\n    tile_provider=\"google_satellite\"\n)\n```\n\n### Grouping and Organization\n\n```python\nfrom map_locations import load_locations_from_yaml, show_locations_grouped\n\nlocations = load_locations_from_yaml(\"locations.yaml\")\n\n# Group by type (default)\nshow_locations_grouped(locations, group_by=\"type\", map_filename=\"type_map.html\")\n\n# Group by neighborhood\nshow_locations_grouped(locations, group_by=\"neighborhood\", map_filename=\"neighborhood_map.html\")\n\n# Group by date added\nshow_locations_grouped(locations, group_by=\"date_added\", map_filename=\"date_map.html\")\n```\n\n**See also**: [Grouping Options](#grouping-options) for CLI examples of all available grouping fields.\n\n### Data Loading\n\n```python\nfrom map_locations import load_locations_from_yaml\n\n# Load locations from YAML file\nlocations = load_locations_from_yaml(\"locations.yaml\")\n\n# Access location data\nfor location in locations:\n    print(f\"Name: {location['name']}\")\n    print(f\"Type: {location.get('type', 'Unknown')}\")\n    print(f\"Tags: {location.get('tags', [])}\")\n    print(f\"Coordinates: {location['latitude']}, {location['longitude']}\")\n```\n\n## Development\n\n### Setup Development Environment\n\n```bash\n# Clone the repository\ngit clone https://github.com/shpigi/map-locations.git\ncd map-locations\n\n# Install with development dependencies\nmake install-dev\n\n# Set up pre-commit hooks\nmake setup-dev\n```\n\n**Note**: This setup is also covered in the [Installation](#installation) section above.\n\n### Running Tests\n\n```bash\n# Run all tests\nmake test\n\n# Run tests with coverage\npytest tests/ -v --cov=map_locations --cov-report=html\n\n# Run specific test file\npytest tests/test_core.py -v\n```\n\n### Code Quality\n\n```bash\n# Format code\nmake format\n\n# Run linting (pre-commit checks on all files)\nmake lint\n\n# Run linting on staged files only\nmake lint-staged\n```\n\n### Pre-commit Hooks\n\nThis project uses pre-commit hooks to ensure code quality. The hooks will automatically run on every commit and include:\n\n- **Code Formatting**: Black for code formatting, isort for import sorting\n- **Linting**: Flake8 for style checking, MyPy for type checking\n- **File Checks**: YAML validation, JSON validation, trailing whitespace removal\n- **Security**: Private key detection, merge conflict detection\n\n#### Setting up pre-commit hooks:\n\n```bash\n# Install pre-commit hooks (automatically done with setup-dev)\nmake setup-dev\n\n# Or manually:\npre-commit install\n```\n\n#### Running pre-commit checks manually:\n\n```bash\n# Run all hooks on all files\npre-commit run --all-files\n\n# Run specific hook\npre-commit run black\n\n# Run hooks on staged files only\npre-commit run\n```\n\n\n\n#### Code Style Standards\n\nThis project follows strict code quality standards:\n\n- **Line Length**: Maximum 100 characters\n- **Formatting**: Black for code formatting, isort for imports\n- **Linting**: Flake8 for style checking\n- **Type Checking**: MyPy for type validation\n- **Documentation**: Google-style docstrings\n\nThe pre-commit hooks will automatically enforce these standards.\n\n### Building and Publishing\n\n```bash\n# Build the package\nmake build\n\n# Clean build artifacts\nmake clean\n\n# Publish to PyPI (requires proper configuration)\nmake publish\n```\n\n### Running Examples\n\n```bash\n# Run the basic usage example\npython examples/basic_usage.py\n\n# Test the CLI\nmake test-cli\n```\n\n## Map Features\n\n### Interactive Elements\n\n- **Clickable Markers**: Click on any location to see detailed popup with name, type, tags, and dates\n- **Zoom Controls**: Zoom in/out with mouse wheel or controls\n- **Pan Navigation**: Click and drag to move around the map\n- **Fullscreen Mode**: Toggle fullscreen view\n- **Layer Control**: Toggle visibility of different groups with the layer control panel\n\n### Color Coding\n\nDifferent groups are automatically assigned colors from a predefined color palette:\n\n- **Group Colors**: Each group (neighborhood, type, etc.) gets a unique color\n- **Color Palette**: Red, blue, green, purple, orange, darkred, lightred, beige, darkblue, darkgreen, cadetblue\n- **Automatic Cycling**: Colors cycle through the palette for multiple groups\n- **Fallback**: Gray color for additional groups beyond the palette\n\n### Popup Information\n\n- **Detailed Popups**: Click any marker to see comprehensive information including:\n  - Location name\n  - Type\n  - Tags\n  - Date added\n  - date of visit\n- **Tooltips**: Hover over markers to see location names\n- **Layer Control**: Toggle visibility of different groups using the layer control panel\n\n## Configuration\n\n### Grouping Options\n\nThe `show_locations_grouped` function allows you to group locations by any field in your YAML:\n\n```python\nfrom map_locations import load_locations_from_yaml, show_locations_grouped\n\nlocations = load_locations_from_yaml(\"locations.yaml\")\n\n# Group by any field\nshow_locations_grouped(locations, group_by=\"type\")          # By type (default)\nshow_locations_grouped(locations, group_by=\"neighborhood\")  # By area\nshow_locations_grouped(locations, group_by=\"date_added\")    # By date\nshow_locations_grouped(locations, group_by=\"tags\")          # By tags\n```\n\n### Map Styling\n\n```python\nfrom map_locations import load_locations_from_yaml, show_locations_grouped\n\nlocations = load_locations_from_yaml(\"locations.yaml\")\n\n# Custom map options\nshow_locations_grouped(\n    locations,\n    group_by=\"type\",\n    map_filename=\"custom_map.html\"\n)\n```\n\n**See also**: [Tile Providers](#tile-providers) for available tile provider options and [Tile Provider Options](#tile-provider-options) for CLI examples.\n\n## Examples\n\n### Paris Passages Map\n\nThe included example shows historic passages in Paris:\n\n```bash\n# Generate the Paris passages map grouped by type (default)\nmap-locations generate --input map_locations/maps/passages/locations.yaml --group-by type --output passages_map.html\n```\n\nThis creates an interactive map of Paris's historic covered passages with:\n- Locations grouped by type (default)\n- Color-coded groups with layer controls\n- Detailed popups showing name, type, tags, and dates\n- Interactive layer panel to toggle group visibility\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Acknowledgments\n\n- Built with [Folium](https://python-visualization.github.io/folium/) for interactive maps\n- Uses [SimpleKML](https://simplekml.readthedocs.io/) for KML export\n- Inspired by the historic passages of Paris\n",
    "bugtrack_url": null,
    "license": "MIT",
    "summary": "A Python library for mapping locations with interactive filtering and visualization capabilities",
    "version": "0.2.1",
    "project_urls": {
        "Bug Tracker": "https://github.com/shpigi/map-locations/issues",
        "Documentation": "https://github.com/shpigi/map-locations#readme",
        "Homepage": "https://github.com/shpigi/map-locations",
        "Repository": "https://github.com/shpigi/map-locations"
    },
    "split_keywords": [
        "maps",
        " locations",
        " folium",
        " yaml",
        " geojson",
        " kml",
        " gis",
        " geospatial",
        " data-visualization",
        " ai-friendly",
        " type-hints",
        " data-analysis"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "49839ba800557d51103e05a477f844deb064e03edec7a6c9ddccdffc614b27ae",
                "md5": "252d6798f0ca765a2979ccea3a98d648",
                "sha256": "001ffb3d9a73f66dbbb7c2e4ad985eebb1cb4d385faebeabdfc2c4beef0dc0b9"
            },
            "downloads": -1,
            "filename": "map_locations-0.2.1-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "252d6798f0ca765a2979ccea3a98d648",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.10",
            "size": 18294,
            "upload_time": "2025-07-20T03:56:33",
            "upload_time_iso_8601": "2025-07-20T03:56:33.941399Z",
            "url": "https://files.pythonhosted.org/packages/49/83/9ba800557d51103e05a477f844deb064e03edec7a6c9ddccdffc614b27ae/map_locations-0.2.1-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "f3452256f04fec2712faf18bc89929d9b0048c8e429c7aeadb8e0f3da8265ede",
                "md5": "5b05346124ea5e69242667f3c057ce71",
                "sha256": "b3a5e83c56c76428bbe3713603c39ea8c3a944c2255249b8d701e2e56131a48e"
            },
            "downloads": -1,
            "filename": "map_locations-0.2.1.tar.gz",
            "has_sig": false,
            "md5_digest": "5b05346124ea5e69242667f3c057ce71",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.10",
            "size": 30141,
            "upload_time": "2025-07-20T03:56:35",
            "upload_time_iso_8601": "2025-07-20T03:56:35.301021Z",
            "url": "https://files.pythonhosted.org/packages/f3/45/2256f04fec2712faf18bc89929d9b0048c8e429c7aeadb8e0f3da8265ede/map_locations-0.2.1.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-07-20 03:56:35",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "shpigi",
    "github_project": "map-locations",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "requirements": [
        {
            "name": "folium",
            "specs": [
                [
                    ">=",
                    "0.14.0"
                ]
            ]
        },
        {
            "name": "pyyaml",
            "specs": [
                [
                    ">=",
                    "6.0"
                ]
            ]
        }
    ],
    "lcname": "map-locations"
}