Overture Maps Import Guide

This guide explains how to import places/POIs from Overture Maps into the Vibemap database.

What is Overture Maps?

Overture Maps Foundation provides open map data with 64+ million places worldwide. The data includes:

• Business names and addresses
• Categories and classifications
• Contact information (websites, phones, emails)
• Geographic coordinates
• Confidence scores for data quality

Data sources include Meta, Microsoft, and PinMeTo, with monthly releases and permissive licensing (CDLA Permissive 2.0).

Installation

Install the required Python packages:

pip install overturemaps geopandas

Quick Start

List available cities

python manage.py import_overture_places --list-cities

Import places for a predefined city

# Import all places in Boston with default settings
python manage.py import_overture_places --city=boston

# Import high-confidence places in San Francisco
python manage.py import_overture_places --city=san_francisco --min-confidence=0.8

# Import only restaurants in Seattle
python manage.py import_overture_places --city=seattle --category=restaurant

Import places using custom bounding box

# Custom area with bounding box (west, south, east, north)
python manage.py import_overture_places --bbox=-71.068,42.353,-71.058,42.363

Command Options

Option	Description	Example
--city	Use predefined city bounding box	--city=boston
--bbox	Custom bounding box: west,south,east,north	--bbox=-71.068,42.353,-71.058,42.363
--min-confidence	Minimum confidence score (0-1)	--min-confidence=0.75
--category	Filter by primary category	--category=restaurant
--limit	Limit number of places to process	--limit=100
--dry-run	Preview without saving to database	--dry-run
--export-geojson	Export results to GeoJSON file	--export-geojson=places.geojson
--skip-existing	Skip places already in database	--skip-existing
--list-cities	Show available predefined cities	--list-cities

Usage Examples

Test run with a small dataset

# Preview 10 places without saving
python manage.py import_overture_places \
    --city=boston \
    --limit=10 \
    --dry-run

Import restaurants only

# Import all restaurants in Austin with high confidence
python manage.py import_overture_places \
    --city=austin \
    --category=restaurant \
    --min-confidence=0.7

Export data for review

# Export to GeoJSON before importing
python manage.py import_overture_places \
    --city=portland \
    --export-geojson=/tmp/portland_places.geojson \
    --dry-run

Full import with quality filters

# Import high-quality places, skip existing, show verbose output
python manage.py import_overture_places \
    --city=chicago \
    --min-confidence=0.8 \
    --skip-existing \
    -v 2

Custom area import

# Import places in a specific neighborhood
python manage.py import_overture_places \
    --bbox=-122.420,37.775,-122.400,37.790 \
    --min-confidence=0.6

Predefined Cities

The following cities have predefined bounding boxes:

• boston - Greater Boston area
• san_francisco - San Francisco city
• new_york - Manhattan and parts of Brooklyn
• los_angeles - Central LA area
• chicago - Chicago downtown and surrounding areas
• seattle - Seattle metropolitan area
• austin - Austin city limits
• denver - Denver metro area
• miami - Miami city area
• portland - Portland, OR metro area
• la_jolla - La Jolla neighborhood
• stevenson - Stevenson, WA area
• toledo - Toledo, OH area
• houston - Greater Houston area
• utica - Utica, NY area
• whittier - Whittier, CA area

Data Fields Imported

The command imports the following fields from Overture Maps:

• name - Primary place name
• location - Geographic coordinates (Point geometry)
• external_id - Overture Maps unique identifier
• street - Street address
• city - City/locality
• state - State/region
• postal_code - Postal/ZIP code
• country - Country code
• website - Primary website URL
• phone - Primary phone number
• data_source - Set to "Overture Maps"

Common Categories

Some useful category filters:

• restaurant - Restaurants and eateries
• cafe - Coffee shops and cafes
• bar - Bars and pubs
• hotel - Hotels and lodging
• museum - Museums and galleries
• park - Parks and recreation areas
• shopping_center - Shopping malls and centers
• grocery_store - Grocery and supermarkets
• pharmacy - Pharmacies and drugstores
• hospital - Hospitals and medical centers

For a complete list of categories, see: Overture Categories Reference

Finding Bounding Boxes

To find coordinates for custom areas:

1. Visit Bounding Box Tool
2. Draw a box around your area of interest
3. Select "CSV" format from the bottom-left dropdown
4. Copy the coordinates in the format: west,south,east,north
5. Use with --bbox option

Example: For a custom area around MIT campus:

python manage.py import_overture_places --bbox=-71.105,42.354,-71.085,42.364

Performance Tips

1. Start small: Use --limit=100 for testing before full imports
2. Use dry-run: Always test with --dry-run first
3. Filter by confidence: Use --min-confidence=0.7 to get higher quality data
4. Skip existing: Use --skip-existing on re-runs to avoid duplicates
5. Export first: Use --export-geojson to inspect data before importing

Troubleshooting

Import is too slow

• Reduce the bounding box size
• Use --limit to process in batches
• Increase --min-confidence to filter out low-quality data

Too many duplicates

• Use --skip-existing flag
• Increase --min-confidence threshold
• Check for places with similar names using Django admin

Missing dependencies error

pip install overturemaps geopandas

"Unknown city" error

Use --list-cities to see available cities, or provide custom --bbox

Logs

Import logs are saved to /tmp/vibemap_logs/import_overture_places_YYYYMMDD_HHMMSS.log

View logs:

tail -f /tmp/vibemap_logs/import_overture_places_*.log

Integration with Existing Commands

This command complements other import commands:

• import_addresses - Import from address CSVs/GeoJSON
• seed_osm_places - Import from OpenStreetMap
• check_listings - Validate imported places

Suggested workflow:

1. Import base data with import_overture_places
2. Supplement with import_addresses for local datasets
3. Run check_listings to validate and enrich data

Data Source Attribution

All places imported through this command are tracked with the "Overture Maps" data source. This allows you to:

• Query places by source: Place.objects.filter(data_source__name='Overture Maps')
• Track data provenance
• Update or remove Overture data separately

License

Overture Maps data is released under the CDLA Permissive 2.0 license, which allows:

• Commercial use
• Modification
• Distribution
• Private use

Resources

• Overture Maps Foundation: https://overturemaps.org
• Documentation: https://docs.overturemaps.org/
• Python SDK GitHub: https://github.com/OvertureMaps/overturemaps-py
• Schema Reference: https://docs.overturemaps.org/schema/reference/places/place/
• Category List: https://github.com/OvertureMaps/schema/blob/main/docs/schema/concepts/by-theme/places/overture_categories.csv

Example Workflow

# 1. Test with a small sample
python manage.py import_overture_places --city=boston --limit=10 --dry-run

# 2. Export for review
python manage.py import_overture_places --city=boston --limit=100 --export-geojson=/tmp/boston_preview.geojson

# 3. Import high-quality places
python manage.py import_overture_places --city=boston --min-confidence=0.8

# 4. Import specific categories
python manage.py import_overture_places --city=boston --category=restaurant --min-confidence=0.7

# 5. Run validation
python manage.py check_listings --city=boston

# 6. View results in Django admin
# Visit /admin/api/place/ and filter by data_source="Overture Maps"

Support

For issues or questions:

• Check logs in /tmp/vibemap_logs/
• Review Overture Maps documentation
• Check the command help: python manage.py import_overture_places --help