mappy-py 0.2.0

mappy

Demo  •  Features  •  Modes  •  Installation  •  Configuration  •  Run  •  Start  •  Data  •  API  •  License

PyPI application

python -m pip install mappy-py
mappy

mappy opens the tabless Windows WebView2 window by default. Windows requires Edge WebView2 Runtime. Standard browser mode uses mappy-browser. The distribution is mappy-py; the Python import remains mappy. Do not install the unrelated PyPI mappy package in the same environment. See installation and PyPI publishing.

mappy is a lightweight Python geospatial framework and Streamlit application for mapping, location enrichment, environmental data retrieval, astronomical data access, web scraping, and geospatial data management. It wraps core mapping services behind a simple Python interface while also exposing the functionality through a wide Streamlit dashboard.

The project supports traditional mapping workflows such as geocoding, distance calculation, static map generation, time-zone lookup, spreadsheet enrichment, and interactive map rendering. It also extends into weather, environmental, astronomical, geological, and web data sources so the same application can support location intelligence, situational awareness, and data pipeline enrichment.

🎥 Demo

☁️ Cloud

✨ Features

• 🔎 Geocoding – Convert free-form addresses or city, state, and country triples into coordinates.
• 🧭 Places Fallback – Use Places text search when geocoding does not resolve a location.
• 📏 Distance Matrix – Compute distance and travel time between origins and destinations.
• 🗺️ Interactive Maps – Render uploaded or geocoded coordinate data with map overlays.
• 🖼️ Static Maps – Generate static map previews and map image URLs for reporting.
• ⏱️ Time Zones – Resolve IANA time zones from latitude and longitude.
• 📊 Excel and CSV Enrichment – Upload spreadsheets and enrich records with geocoded coordinates.
• 🗄️ SQLite Data Management – Browse, insert, update, delete, geocode, profile, and query local tables.
• 🌦️ Weather Data – Query Google Weather, OpenWeather/Open-Meteo, historical weather, climate data, tides, and current data.
• 🌫️ Environmental Data – Query air quality, UV index, EPA EnviroFacts, PurpleAir, NASA FIRMS, and NASA EONET data.
• 🌌 Astronomical Data – Access naval observatory, space weather, star chart, satellite, catalog, AstroQuery/SIMBAD, and star map functionality.
• 🌎 Geological Data – Query USGS earthquakes, water data, national map data, and global imagery.
• 🧠 GIS Retrieval – Process every Web, Weather, Environmental, Astronomical, and Geological source through combined chunking and word tokenization, embedding, storage, and retrieval controls. Review the active source document, chunks, and full embedding vectors in read-only result tabs.
• 🕸️ Web Scraper – Fetch, crawl, parse, summarize, and extract structured data from web pages.
• ⚡ Rate Limiting and Caching – Control API usage with QPS limits and optional cache backends.
• 🛠️ Explicit Error Handling – Use clear exception paths for not-found, gateway, and framework errors.

🧭 Application Modes

The Streamlit application is organized around the following modes.

🧩 Sidebar

The application sidebar provides the main operating controls.

🔑 API Set-up

• Science APIs
• OpenAI
• Gemini AI
• Grok AI
• Mistral AI
• Claude AI

📦 Installation

Clone the repository and install dependencies.

git clone https://github.com/is-leeroy-jenkins/Mappy.git
cd Mappy
python -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -r requirements.txt

For Linux or macOS:

git clone https://github.com/is-leeroy-jenkins/Mappy.git
cd Mappy
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt

🔑 Configuration

mappy reads configuration values from the current process environment and config.py. Values entered in the Streamlit Credentials panel update the environment for the active session.

🚀 Running the Streamlit App

Start the application from the repository root.

streamlit run app.py

The app uses a wide layout and opens with the sidebar expanded. Select a mode from **🛰️ GIS Mapping ** and then configure the relevant location, credentials, and data inputs from the sidebar and mode-specific expanders.

🚀 Quick Start: Python Framework

1. Initialize Maps

from mappy import Maps

maps = Maps(api_key="YOUR_API_KEY")

2. Geocode an address

from mappy import Geocoder

geo = Geocoder(maps)
result = geo.freeform("Paris, France")
print(result["lat"], result["lng"], result["formatted_address"])

3. Calculate distance

from mappy import DistanceMatrix

dist = DistanceMatrix(maps)
distance = dist.summary("New York, USA", "Los Angeles, USA", mode="driving")
print(distance["distance_text"], distance["duration_text"])

4. Get a static map URL

from mappy import StaticMapURL

static_map = StaticMapURL(api_key="YOUR_API_KEY")
url = static_map.pin(lat=48.8584, lng=2.2945, zoom=14)
print(url)

5. Process Excel locations

from mappy import Excel

excel = Excel(api_key="YOUR_API_KEY")
excel.enrich(
    input_path="locations.xlsx",
    output_path="locations_with_coords.xlsx",
    city_col="City",
    state_col="State",
    country_col="Country"
)

🗄️ Data Management

The application includes a SQLite management mode for local data workflows. It can:

• Preview the current table.
• Insert rows.
• Update rows.
• Delete rows.
• Profile table data.
• Drop selected tables.
• Create custom tables.
• Inspect table columns and indexes.
• Run SQL through the SQL console.
• Locate report rows missing coordinates.
• Geocode missing report coordinates and write latitude/longitude values back to the database.

This mode is especially useful for datasets with columns similar to:

📂 Project Structure

mappy/
 ├── app.py              # Streamlit application
 ├── config.py           # Application constants, paths, keys, and modes
 ├── maps.py             # Maps API gateway
 ├── geocode.py          # Address and location geocoding
 ├── places.py           # Places text-search fallback
 ├── distances.py        # Distance Matrix support
 ├── timezones.py        # Time-zone resolution
 ├── staticmaps.py       # Static map URL generation
 ├── excel.py            # Excel and CSV integration helpers
 ├── caches.py           # In-memory and SQLite cache backends
 ├── fetchers.py         # Weather, environmental, astronomical, geological, and web fetchers
 ├── loaders.py          # Local document loaders
 ├── embedders.py        # Hosted and local embedding providers
 ├── processing.py       # Source processing controls and result tabs
 ├── vector.py           # Chroma and Pinecone lifecycle and retrieval operations
 ├── exceptions.py       # Custom framework exceptions
 ├── requirements.txt    # Python dependencies
 └── resources/          # Images, setup documentation, and supporting assets

⚠️ Error Handling

• NotFound – Raised when a location cannot be resolved.
• GatewayError – Raised when HTTP or API communication fails.
• MappyError – Base class for framework-level exceptions.

By catching these explicitly, bulk geocoding, file enrichment, and API-backed workflows can fail cleanly without losing the rest of the processing run.

💡 Design Philosophy

• Simplicity first – Each framework class has a single clear responsibility.
• Composable services – Geocoding, distance, maps, time zones, cache, and fetcher services can be used alone or together.
• Streamlit-first operations – The app exposes common workflows through mode-specific controls rather than forcing command-line use.
• Cache-friendly design – Optional in-memory and SQLite cache support reduces repeated API calls.
• Rate-aware calls – QPS controls help protect API quotas.
• Spreadsheet-ready workflows – Excel and CSV support is built into the application.
• Data-management capable – SQLite tooling supports local enrichment, auditing, and iterative cleanup.

🧪 Example Use Cases

• Enriching customer, facility, incident, or report datasets with GPS coordinates.
• Calculating travel distances for relocation, service coverage, logistics, or routing analysis.
• Creating static map thumbnails for reports, dashboards, or case summaries.
• Validating and normalizing international addresses.
• Auditing time-zone coverage for scheduling or distributed operations.
• Mapping weather, environmental, geological, or astronomical data around a selected location.
• Updating local SQLite tables with missing latitude and longitude values.
• Scraping web pages into structured text, links, and metadata for downstream analysis.

🔑 API Key References

AI API Keys

• OpenAI API Key
• Grok API Key
• Gemini API Key

Data Services

📚 Dependencies

Core dependencies include:

Additional dependencies may be required by optional fetchers or provider-specific workflows.

📜 License

Mappy is available under the MIT License here.