Transform any location into museum-quality cartographic art.
A web application that generates beautiful, minimalist map posters for any city in the world. Powered by OpenStreetMap data and secured with x402 micropayments on Base.
Live Demo · 17 Themes · API Docs
- Any City, Anywhere — Search for any location worldwide using Photon geocoding
- 17 Curated Themes — From minimalist Japanese ink to vibrant neon cyberpunk
- Smart Sizing — Auto-detects optimal map radius based on city importance
- High Resolution — 300 DPI output ready for printing
- Crypto Payments — $0.10 USDC via x402 protocol on Base
- Real-time Progress — WebSocket updates during generation
- Community Gallery — Browse and get inspired by others' creations
| City | Theme | Preview |
|---|---|---|
| San Francisco | Sunset | |
| Barcelona | Warm Beige |  |
| Venice | Blueprint | |
| Tokyo | Japanese Ink | |
| Singapore | Neon Cyberpunk | |
| Dubai | Midnight Blue |  |
- Search — Enter any city name and select from autocomplete suggestions
- Customize — Choose a theme and map scale
- Pay — Connect your wallet and pay $0.10 USDC
- Generate — Watch real-time progress as your poster is rendered
- Download — Get your high-resolution PNG ready for printing
- Frontend: Vanilla JS, Vite, Web3Modal/Reown AppKit
- Backend: Node.js, Express, WebSocket
- Payments: x402 Protocol with Coinbase CDP
- Map Generation: Python, OSMnx, Matplotlib
- Data: OpenStreetMap via Overpass API
- Geocoding: Photon (Komoot)
- Node.js 22+
- Python 3.11+
- A wallet with USDC on Base (for testing payments)
# Clone the repository
git clone https://github.com/Ashe-Oro/cartographART.git
cd cartographART
# Install Python dependencies
pip install -r requirements.txt
# Install Node.js dependencies
cd server && npm install && cd ..
# Install frontend dependencies (optional, for rebuilding)
npm installCreate a .env file in the project root:
# Required for mainnet payments
PAY_TO_ADDRESS=0xYourWalletAddress
CDP_API_KEY_ID=your_cdp_key_id
CDP_API_KEY_SECRET=your_cdp_key_secret
# Optional
MODE=mainnet
POSTER_PRICE=0.10
PORT=8080# Start the server
cd server && npm start
# Or with auto-reload
cd server && npm run devOpen http://localhost:8080 in your browser.
npm run buildPOST /api/postersRequires x402 payment header with $0.10 USDC.
Request Body:
{
"city": "San Francisco",
"state": "California",
"country": "United States",
"theme": "sunset",
"size": "city",
"showInGallery": true
}Response:
{
"job_id": "abc123",
"status": "pending",
"message": "Poster generation started"
}GET /api/jobs/:jobIdws://localhost:8080/ws/jobs/:jobId
Receive real-time progress updates:
{
"type": "job_update",
"status": "processing",
"progress": 45,
"message": "Rendering map..."
}GET /api/posters/:jobId| Endpoint | Method | Description |
|---|---|---|
/health |
GET | Health check |
/api/themes |
GET | List available themes |
/api/gallery |
GET | Get community gallery |
/api/gallery/thumbnail/:jobId |
GET | Get poster thumbnail |
/api/gallery/image/:jobId |
GET | Get full poster image |
Cartograph is designed to be accessible to AI agents and LLMs:
| Endpoint | Description |
|---|---|
/index.html.md |
Markdown version of homepage (llmstxt.org spec) |
/openapi.json |
OpenAPI 3.1 specification |
/robots.txt |
Allows AI crawlers (GPTBot, anthropic-ai, etc.) |
/.well-known/x402 |
x402 payment discovery (pricing, network, docs) |
17 themes available in the themes/ directory:
| Theme | Description | Colors |
|---|---|---|
feature_based |
Classic black & white with road hierarchy | Black/White |
noir |
Pure black background, crisp white roads | Black/White |
midnight_blue |
Navy background with gold accent roads | Navy/Gold |
blueprint |
Architectural blueprint aesthetic | Blue/White |
neon_cyberpunk |
Dark with electric pink and cyan | Black/Pink/Cyan |
warm_beige |
Vintage sepia tones | Cream/Brown |
japanese_ink |
Minimalist ink wash style | Cream/Black |
pastel_dream |
Soft muted pastels | Pink/Lavender |
forest |
Deep greens and sage | Green/Cream |
ocean |
Blues and teals for coastal cities | Blue/Teal |
terracotta |
Mediterranean warmth | Orange/Brown |
sunset |
Warm oranges and pinks | Orange/Pink |
autumn |
Seasonal burnt oranges and reds | Orange/Red |
copper_patina |
Oxidized copper aesthetic | Teal/Copper |
monochrome_blue |
Single blue color family | Blue |
gradient_roads |
Smooth gradient shading | Various |
contrast_zones |
High contrast urban density | Black/White |
Add a JSON file to the themes/ directory:
{
"name": "My Theme",
"description": "Description of the theme",
"bg": "#FFFFFF",
"text": "#000000",
"water": "#C0C0C0",
"parks": "#F0F0F0",
"road_motorway": "#0A0A0A",
"road_primary": "#1A1A1A",
"road_secondary": "#2A2A2A",
"road_tertiary": "#3A3A3A",
"road_residential": "#4A4A4A",
"road_default": "#3A3A3A"
}| Preset | Distance | Best For |
|---|---|---|
neighborhood |
2km | Dense urban cores, specific districts |
small |
4km | Small towns, historic centers |
town |
6km | Towns, focused city areas |
city |
12km | Standard city view (default) |
metro |
20km | Large metropolitan areas |
region |
35km | Wide regional overview |
Generate posters directly from the command line:
python create_map_poster.py --city "New York" --country "USA" --theme noir --size city| Option | Short | Description | Default |
|---|---|---|---|
--city |
-c |
City name | required |
--country |
-C |
Country name | required |
--state |
-s |
State/region | optional |
--theme |
-t |
Theme name | feature_based |
--size |
Size preset | auto | |
--distance |
-d |
Custom radius in meters | auto |
--output |
-o |
Output file path | auto |
--preview |
Low-res 72 DPI preview | false | |
--list-themes |
List all themes |
This project is configured for deployment on Railway:
- Connect your GitHub repository
- Add environment variables in Railway dashboard
- Attach a volume at
/app/server/datafor persistence - Deploy
The included railway.json and Dockerfile handle the build configuration.
MODE=mainnet
PAY_TO_ADDRESS=0xYourAddress
CDP_API_KEY_ID=your_key
CDP_API_KEY_SECRET=your_secret
CDP_WALLET_SECRET=your_wallet_secret┌─────────────────────────────────────────────────────────────────┐
│ Frontend │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────────┐ │
│ │ Search │ │ Themes │ │ Wallet │ │ Progress/Result │ │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────────┬─────────┘ │
└───────┼─────────────┼─────────────┼─────────────────┼───────────┘
│ │ │ │
▼ ▼ ▼ ▼
┌─────────────────────────────────────────────────────────────────┐
│ Node.js Server │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────────────┐ │
│ │ Photon │ │ Themes │ │ x402 │ │ WebSocket │ │
│ │ Proxy │ │ API │ │ Payments │ │ Updates │ │
│ └──────────┘ └──────────┘ └────┬─────┘ └────────┬─────────┘ │
└───────────────────────────────────┼─────────────────┼───────────┘
│ │
▼ │
┌─────────────────────────────────────────────────────┼───────────┐
│ Python Generator │ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │
│ │ Nominatim│ │ OSMnx │ │Matplotlib│──────────┘ │
│ │ Geocode │ │ Fetch │ │ Render │ │
│ └──────────┘ └──────────┘ └──────────┘ │
└─────────────────────────────────────────────────────────────────┘
- Map data © OpenStreetMap contributors
- Geocoding by Photon (Komoot)
- Graph analysis by OSMnx
- Payments via x402 Protocol on Base
This project is licensed under CC BY-NC 4.0 (Creative Commons Attribution-NonCommercial 4.0 International).
You are free to share and adapt this work for non-commercial purposes with attribution. See LICENSE for details.
Cartograph — Bespoke City Prints
cartograph.art