Location

Customize Location (Map Region)

WARNING: This subskill cannot be run independently. It must be invoked from the routing-customization router. It does not restart services, rebuild graphs, update MAP_CONFIG, or redeploy the Function Tester -- the router handles all of those in Steps 4-6 after this subskill completes.

Downloads a new OpenStreetMap region map and update the configuration files.

This skill handles:

1. Downloading the map data from Geofabrik or BBBike
2. Updating ors-config.yml with the new map path
3. Updating service specifications for the new region

Prerequisites

• Active Snowflake connection
• OpenRouteService App deployed
• Compute resources for map download and graph building

Input Parameters

• <REGION_NAME>: Target region name selected by user (e.g., "great-britain", "switzerland", "new-york")
• <MAP_NAME>: OSM file name (e.g., "great-britain-latest.osm.pbf")
• <URL>: Download URL from geofabrik.de or bbbike.org

Error Logging

Follow the Error Logging convention in AGENTS.md. Log file prefix: routing-customization.

Workflow

Step 1: Suspend Compute Pool

Goal: Suspend the compute pool to allow configuration changes

Actions:

1. Suspend the compute pool (required before altering INSTANCE_FAMILY or other properties):

   ALTER COMPUTE POOL OPENROUTESERVICE_APP_COMPUTE_POOL SUSPEND;
   

Output: Compute pool suspended

Step 2: Download Map Data (replaces old Notebook workflow)

Goal: Download OSM map data locally and upload to Snowflake stage

Note: This step no longer requires a Snowflake Notebook, compute pool, or external access integration. The download runs locally via a Python script.

Step 3: Download Map Data

Goal: Download OSM map data and upload to Snowflake stage

Actions:

1. Check if map already exists:

   ALTER STAGE OPENROUTESERVICE_APP.CORE.ORS_SPCS_STAGE REFRESH; 
   LS @OPENROUTESERVICE_APP.CORE.ORS_SPCS_STAGE;
   

   • If map exists, ask user if they want to re-download

2. Run the download script from install-fleet-apps/scripts/:

   python download_map.py \
     "https://download.geofabrik.de/europe/<region>-latest.osm.pbf" \
     "<region>-latest.osm.pbf" \
     "<region>" \
     --connection <connection>
   

   Parameters:

   • First arg: URL of OSM PBF file (e.g., https://download.geofabrik.de/europe/switzerland-latest.osm.pbf)
   • Second arg: File name (e.g., switzerland-latest.osm.pbf)
   • Third arg: Region folder name on stage (e.g., switzerland)
   • --connection: Snowflake connection name

   Note: Large maps (>1GB) will take time to download. The script shows progress.

3. Check downloaded map size and suggest resource scaling:

   LS @OPENROUTESERVICE_APP.CORE.ORS_SPCS_STAGE/<REGION_NAME>/;
   

   • 1GB - 5GB maps: Suggest scaling up compute:

     ALTER COMPUTE POOL OPENROUTESERVICE_APP_COMPUTE_POOL SET INSTANCE_FAMILY = HIGHMEM_X64_M;
     ALTER SERVICE OPENROUTESERVICE_APP.CORE.ORS_SERVICE SET AUTO_SUSPEND_SECS = 28800;
     

   • 5GB+ maps: Suggest larger scaling:

     ALTER COMPUTE POOL OPENROUTESERVICE_APP_COMPUTE_POOL SET INSTANCE_FAMILY = HIGHMEM_X64_M;
     ALTER SERVICE OPENROUTESERVICE_APP.CORE.ORS_SERVICE SET AUTO_SUSPEND_SECS = 86400;
     

Output: Map data downloaded to stage

Step 4: Update Configuration

Goal: Modify ors-config.yml to reference new map file

Actions:

Option A - Using WRITE_ORS_CONFIG (recommended):

CALL OPENROUTESERVICE_APP.CORE.WRITE_ORS_CONFIG(
    '<REGION_NAME>',
    '<MAP_NAME>',
    'driving-car,driving-hgv,cycling-electric'  -- comma-separated profiles to enable
);

Option B - Manual editing (fallback):

1. Edit .cortex/skills/install-fleet-apps/openrouteservice_app/staged_files/ors-config.yml:

   • Change source_file: /home/ors/files/{old-map}
   • To: source_file: /home/ors/files/<MAP_NAME>

2. Upload to stage:

   snow stage copy .cortex/skills/install-fleet-apps/openrouteservice_app/staged_files/ors-config.yml @OPENROUTESERVICE_APP.CORE.ORS_SPCS_STAGE/<REGION_NAME>/ --connection <ACTIVE_CONNECTION> --overwrite
   

Output: Configuration updated

Step 5: Update Service Specification

Goal: Reconfigure ORS service to point to new map region

Actions:

1. Edit .cortex/skills/install-fleet-apps/openrouteservice_app/services/openrouteservice/openrouteservice.yaml:

   • Update all volume source paths to new region:

     volumes:
       - name: files
         source: "@CORE.ORS_SPCS_STAGE/<REGION_NAME>"
       - name: graphs
         source: "@CORE.ORS_GRAPHS_SPCS_STAGE/<REGION_NAME>"
       - name: elevation-cache
         source: "@CORE.ORS_ELEVATION_CACHE_SPCS_STAGE/<REGION_NAME>"
     

2. Upload specification:

   snow stage copy .cortex/skills/install-fleet-apps/openrouteservice_app/services/openrouteservice/openrouteservice.yaml @openrouteservice_app.core.ors_spcs_stage/services/openrouteservice/ --connection <ACTIVE_CONNECTION> --overwrite
   

3. Update service with new specification:

   ALTER SERVICE OPENROUTESERVICE_APP.CORE.ORS_SERVICE
   FROM @OPENROUTESERVICE_APP.CORE.ORS_SPCS_STAGE/services/openrouteservice/
   SPECIFICATION_FILE = 'openrouteservice.yaml';
   

_IMPORTANT: REBUILD_GRAPHS is managed automatically (Issue #59). Do not manually toggle it in openrouteservice.yaml. The default region service uses REBUILD_GRAPHS: "false" and reuses graphs persisted on @ORS_GRAPHS_SPCS_STAGE. For Region Builder regions, the provisioner probes the stage on first create (true if empty, false otherwise) and auto-flips to false after the first successful build.

To force a rebuild (e.g. after a PBF update or corruption), use:

CALL OPENROUTESERVICE_APP.CORE.REBUILD_REGION_GRAPHS('<region>');

This flips the flag, cycles the service, waits for readiness, and flips back.

Output: Service configured for new region

Choosing a Map Size

When the user asks to change location, always ask if they want a city-only map or a larger region:

"Do you want just the city of Paris (faster download, quicker graph build) or the entire France region (larger coverage, longer build time)?"

• City maps (~50-200MB): Faster to download, quicker graph builds (5-15 min), perfect for demos
• Country/Region maps (1-10GB): Full coverage, longer build times (1-8 hours), better for production

City-Specific Maps (BBBike.org)

For city-only maps, use BBBike.org which offers pre-built city extracts:

TIP: Browse all available cities at: https://download.bbbike.org/osm/bbbike/

Country/Region Maps (Geofabrik)

For full country or region coverage, use Geofabrik:

TIP: Browse all regions at: https://download.geofabrik.de/

Stopping Points

• ✋ After Step 2: Verify notebook was created without errors
• ✋ After Step 3: Confirm map download completed and check file size for resource scaling
• ✋ After Step 5: Verify service specification uploaded before returning to router

Return to Router

After completing all steps in this subskill, return to the routing-customization router and continue from Step 4: Update Routing Graphs. This subskill does NOT restart services or rebuild graphs -- the router handles that.

Output

Map region changed to <REGION_NAME>.