LogoLogo
HomeAcademyLoginTry for free
  • Welcome
  • What's new
    • Q2 2025
    • Q1 2025
    • Q4 2024
    • Q3 2024
    • Q2 2024
    • Q1 2024
    • Q4 2023
    • Q3 2023
    • Q2 2023
    • Q1 2023
    • Q4 2022
    • Q3 2022
  • FAQs
    • Accounts
    • Migration to the new platform
    • User & organization setup
    • General
    • Builder
    • Workflows
    • Data Observatory
    • Analytics Toolbox
    • Development Tools
    • Deployment Options
    • CARTO Basemaps
    • CARTO for Education
    • Support Packages
    • Security and Compliance
  • Getting started
    • What is CARTO?
    • Quickstart guides
      • Connecting to your data
      • Creating your first map
      • Creating your first workflow
      • Developing your first application
    • CARTO Academy
  • CARTO User Manual
    • Overview
      • Creating your CARTO organization
      • CARTO Cloud Regions
      • CARTO Workspace overview
    • Maps
      • Data sources
        • Simple features
        • Spatial Indexes
        • Pre-generated tilesets
        • Rasters
        • Defining source spatial data
        • Managing data freshness
        • Changing data source location
      • Layers
        • Point
          • Grid point aggregation
          • H3 point aggregation
          • Heatmap point aggregation
          • Cluster point aggregation
        • Polygon
        • Line
        • Grid
        • H3
        • Raster
        • Zoom to layer
      • Widgets
        • Formula widget
        • Category widget
        • Pie widget
        • Histogram widget
        • Range widget
        • Time Series widget
        • Table widget
      • SQL Parameters
        • Date parameter
        • Text parameter
        • Numeric parameter
        • Publishing SQL parameters
      • Interactions
      • Legend
      • Basemaps
        • Basemap selector
      • AI Agents
      • SQL analyses
      • Map view modes
      • Map description
      • Feature selection tool
      • Search locations
      • Measure distances
      • Exporting data
      • Download PDF reports
      • Managing maps
      • Sharing and collaboration
        • Editor collaboration
        • Map preview for editors
        • Map settings for viewers
        • Comments
        • Embedding maps
        • URL parameters
      • Performance considerations
    • Workflows
      • Workflow canvas
      • Results panel
      • Components
        • Aggregation
        • Custom
        • Data Enrichment
        • Data Preparation
        • Generative AI
        • Input / Output
        • Joins
        • Parsers
        • Raster Operations
        • Spatial Accessors
        • Spatial Analysis
        • Spatial Constructors
        • Spatial Indexes
        • Spatial Operations
        • Statistics
        • Tileset Creation
        • BigQuery ML
        • Snowflake ML
        • Google Earth Engine
        • Google Environment APIs
        • Telco Signal Propagation Models
      • Data Sources
      • Scheduling workflows
      • Sharing workflows
      • Using variables in workflows
      • Executing workflows via API
      • Temporary data in Workflows
      • Extension Packages
      • Managing workflows
      • Workflows best practices
    • Data Explorer
      • Creating a map from your data
      • Importing data
        • Importing rasters
      • Geocoding data
      • Optimizing your data
    • Data Observatory
      • Terminology
      • Browsing the Spatial Data Catalog
      • Subscribing to public and premium datasets
      • Accessing free data samples
      • Managing your subscriptions
      • Accessing your subscriptions from your data warehouse
        • Access data in BigQuery
        • Access data in Snowflake
        • Access data in Databricks
        • Access data in Redshift
        • Access data in PostgreSQL
    • Connections
      • Google BigQuery
      • Snowflake
      • Databricks
      • Amazon Redshift
      • PostgreSQL
      • CARTO Data Warehouse
      • Sharing connections
      • Deleting a connection
      • Required permissions
      • IP whitelisting
      • Customer data responsibilities
    • Applications
    • Settings
      • Understanding your organization quotas
      • Activity Data
        • Activity Data Reference
        • Activity Data Examples
        • Activity Data Changelog
      • Users and Groups
        • Inviting users to your organization
        • Managing user roles
        • Deleting users
        • SSO
        • Groups
        • Mapping groups to user roles
      • CARTO Support Access
      • Customizations
        • Customizing appearance and branding
        • Configuring custom color palettes
        • Configuring your organization basemaps
        • Enabling AI Agents
      • Advanced Settings
        • Managing applications
        • Configuring S3 Bucket for Redshift Imports
        • Configuring OAuth connections to Snowflake
        • Configuring OAuth U2M connections to Databricks
        • Configuring S3 Bucket integration for RDS for PostgreSQL Exports in Builder
        • Configuring Workload Identity Federation for BigQuery
      • Data Observatory
      • Deleting your organization
    • Developers
      • Managing Credentials
        • API Base URL
        • API Access Tokens
        • SPA OAuth Clients
        • M2M OAuth Clients
      • Named Sources
  • Data and Analysis
    • Analytics Toolbox Overview
    • Analytics Toolbox for BigQuery
      • Getting access
        • Projects maintained by CARTO in different BigQuery regions
        • Manual installation in your own project
        • Installation in a Google Cloud VPC
        • Core module
      • Key concepts
        • Tilesets
        • Spatial indexes
      • SQL Reference
        • accessors
        • clustering
        • constructors
        • cpg
        • data
        • http_request
        • import
        • geohash
        • h3
        • lds
        • measurements
        • placekey
        • processing
        • quadbin
        • random
        • raster
        • retail
        • routing
        • s2
        • statistics
        • telco
        • tiler
        • transformations
      • Guides
        • Running queries from Builder
        • Working with Raster data
      • Release notes
      • About Analytics Toolbox regions
    • Analytics Toolbox for Snowflake
      • Getting access
        • Native App from Snowflake's Marketplace
        • Manual installation
      • Key concepts
        • Spatial indexes
        • Tilesets
      • SQL Reference
        • accessors
        • clustering
        • constructors
        • data
        • http_request
        • import
        • h3
        • lds
        • measurements
        • placekey
        • processing
        • quadbin
        • random
        • raster
        • retail
        • s2
        • statistics
        • tiler
        • transformations
      • Guides
        • Running queries from Builder
        • Working with Raster data
      • Release Notes
    • Analytics Toolbox for Databricks
      • Getting access
        • Personal (former Single User) cluster
        • Standard (former Shared) cluster
      • Reference
        • lds
        • tiler
      • Guides
      • Release Notes
    • Analytics Toolbox for Redshift
      • Getting access
        • Manual installation in your database
        • Installation in an Amazon Web Services VPC
        • Core version
      • Key concepts
        • Tilesets
        • Spatial indexes
      • SQL Reference
        • clustering
        • constructors
        • data
        • http_request
        • import
        • lds
        • placekey
        • processing
        • quadbin
        • random
        • s2
        • statistics
        • tiler
        • transformations
      • Guides
        • Running queries from Builder
      • Release Notes
    • Analytics Toolbox for PostgreSQL
      • Getting access
        • Manual installation
        • Core version
      • Key concepts
        • Tilesets
        • Spatial Indexes
      • SQL Reference
        • h3
        • quadbin
        • tiler
      • Guides
        • Creating spatial index tilesets
        • Running queries from Builder
      • Release Notes
    • CARTO + Python
      • Installation
      • Authentication Methods
      • Visualizing Data
      • Working with Data
        • How to work with your data in the CARTO Data Warehouse
        • How to access your Data Observatory subscriptions
        • How to access CARTO's Analytics Toolbox for BigQuery and create visualizations via Python notebooks
        • How to access CARTO’s Analytics Toolbox for Snowflake and create visualizations via Python notebooks
        • How to visualize data from Databricks
      • Reference
    • CARTO QGIS Plugin
  • CARTO for Developers
    • Overview
    • Key concepts
      • Architecture
      • Libraries and APIs
      • Authentication methods
        • API Access Tokens
        • OAuth Access Tokens
        • OAuth Clients
      • Connections
      • Data sources
      • Visualization with deck.gl
        • Basemaps
          • CARTO Basemap
          • Google Maps
            • Examples
              • Gallery
              • Getting Started
              • Basic Examples
                • Hello World
                • BigQuery Tileset Layer
                • Data Observatory Tileset Layer
              • Advanced Examples
                • Arc Layer
                • Extrusion
                • Trips Layer
            • What's New
          • Amazon Location
            • Examples
              • Hello World
              • CartoLayer
            • What's New
        • Rapid Map Prototyping
      • Charts and widgets
      • Filtering and interactivity
      • Summary
    • Quickstart
      • Make your first API call
      • Visualize your first dataset
      • Create your first widget
    • Guides
      • Build a public application
      • Build a private application
      • Build a private application using SSO
      • Visualize massive datasets
      • Integrate CARTO in your existing application
      • Use Boundaries in your application
      • Avoid exposing SQL queries with Named Sources
      • Managing cache in your CARTO applications
    • Reference
      • Deck (@deck.gl reference)
      • Data Sources
        • vectorTableSource
        • vectorQuerySource
        • vectorTilesetSource
        • h3TableSource
        • h3QuerySource
        • h3TilesetSource
        • quadbinTableSource
        • quadbinQuerySource
        • quadbinTilesetSource
        • rasterSource
        • boundaryTableSource
        • boundaryQuerySource
      • Layers (@deck.gl/carto)
      • Widgets
        • Data Sources
        • Server-side vs. client-side
        • Models
          • getFormula
          • getCategories
          • getHistogram
          • getRange
          • getScatter
          • getTimeSeries
          • getTable
      • Filters
        • Column filters
        • Spatial filters
      • CARTO APIs Reference
    • Release Notes
    • Examples
    • CARTO for React
      • Guides
        • Getting Started
        • Views
        • Data Sources
        • Layers
        • Widgets
        • Authentication and Authorization
        • Basemaps
        • Look and Feel
        • Query Parameters
        • Code Generator
        • Sample Applications
        • Deployment
        • Upgrade Guide
      • Examples
      • Library Reference
        • Introduction
        • API
        • Auth
        • Basemaps
        • Core
        • Redux
        • UI
        • Widgets
      • Release Notes
  • CARTO Self-Hosted
    • Overview
    • Key concepts
      • Architecture
      • Deployment requirements
    • Quickstarts
      • Single VM deployment (Kots)
      • Orchestrated container deployment (Kots)
      • Advanced Orchestrated container deployment (Helm)
    • Guides
      • Guides (Kots)
        • Configure your own buckets
        • Configure an external in-memory cache
        • Enable Google Basemaps
        • Enable the CARTO Data Warehouse
        • Configure an external proxy
        • Enable BigQuery OAuth connections
        • Configure Single Sign-On (SSO)
        • Use Workload Identity in GCP
        • High availability configuration for CARTO Self-hosted
        • Configure your custom service account
      • Guides (Helm)
        • Configure your own buckets (Helm)
        • Configure an external in-memory cache (Helm)
        • Enable Google Basemaps (Helm)
        • Enable the CARTO Data Warehouse (Helm)
        • Configure an external proxy (Helm)
        • Enable BigQuery OAuth connections (Helm)
        • Configure Single Sign-On (SSO) (Helm)
        • Use Workload Identity in GCP (Helm)
        • Use EKS Pod Identity in AWS (Helm)
        • Enable Redshift imports (Helm)
        • Migrating CARTO Self-hosted installation to an external database (Helm)
        • Advanced customizations (Helm)
        • Configure your custom service account (Helm)
    • Maintenance
      • Maintenance (Kots)
        • Updates
        • Backups
        • Uninstall
        • Rotating keys
        • Monitoring
        • Change the Admin Console password
      • Maintenance (Helm)
        • Monitoring (Helm)
        • Rotating keys (Helm)
        • Uninstall (Helm)
        • Backups (Helm)
        • Updates (Helm)
    • Support
      • Get debug information for Support (Kots)
      • Get debug information for Support (Helm)
    • CARTO Self-hosted Legacy
      • Key concepts
        • Architecture
        • Deployment requirements
      • Quickstarts
        • Single VM deployment (docker-compose)
      • Guides
        • Configure your own buckets
        • Configure an external in-memory cache
        • Enable Google Basemaps
        • Enable the CARTO Data Warehouse
        • Configure an external proxy
        • Enable BigQuery OAuth connections
        • Configure Single Sign-On (SSO)
        • Enable Redshift imports
        • Configure your custom service account
        • Advanced customizations
        • Migrating CARTO Self-Hosted installation to an external database
      • Maintenance
        • Updates
        • Backups
        • Uninstall
        • Rotating keys
        • Monitoring
      • Support
    • Release Notes
  • CARTO Native App for Snowflake Containers
    • Deploying CARTO using Snowflake Container Services
  • Get Help
    • Legal & Compliance
    • Previous libraries and components
    • Migrating your content to the new CARTO platform
Powered by GitBook
On this page
  • ROUTING_MATRIX
  • ROUTING_ISOLINES

Was this helpful?

Export as PDF
  1. Data and Analysis
  2. Analytics Toolbox for BigQuery
  3. SQL Reference

routing

BETA

PreviousretailNexts2

Last updated 19 days ago

Was this helpful?

This module contains functions that perform routing and path calculations natively in BigQuery without the need of calling external location data services. In order to run the functions of this module the user needs to have access to CARTO's pre-generated (based on OSM segments) that is available as a public subscription via the Data Observatory. Please check to learn how to subscribe to a dataset from the Data Observatory.

ROUTING_MATRIX

ROUTING_MATRIX(start_point_array, dest_point_array, area_of_interest, transportation_mode, do_network_table, do_source, output_table, options)

Description

This procedure calculates the shortest paths in terms of travel times or distances for all routes between all of a given set of locations. It requires a Data Observatory road network subscription to perform the calculations.

For every given origin, this procedure calculates the minimum cost of travel from that origin to every given destination on the road network specified.

  • start_point_array: ARRAY<GEOGRAPHY> Source points array. the node of the network nearest to this point will be used as the source point to compute the shortest path.

  • dest_point_array: ARRAY<GEOGRAPHY> destination points array. the node of the network nearest to this point will be used as the destination point to compute the shortest path.

  • area_of_interest: GEOGRAPHY area of interest over where the analysis takes place.

  • transportation_mode: STRING type of transportation mode to be used for the calculation of routes. Available options: car, car_motorway_only, car_major_road_only, bicycle or foot.

  • do_network_table: STRING identifier (slug) of the Data Observatory Network table.

  • do_source: STRING name of the location where the Data Observatory subscriptions of the user are stored, in <my-dataobs-project>.<my-dataobs-dataset> format. If only the <my-dataobs-dataset> is included, it uses the project carto-data by default. It can be set to NULL or ''.

  • output_table: STRING the full path name of the output table.

  • options: STRING containing a valid JSON with the different options. Valid options are described the table below. If options is set to NULL the all options are set to default.

Option
Type
Default
Description

TYPE

STRING

time

Defines the kind of optimisation for pathfinding. Possible values: "time", "distance".

MAX_COST

FLOAT64

NULL

Defines maximum cost for pathfinding. If NULL all snapping distance are allowed.

WITH_PATH

BOOL

TRUE

If True returns paths and detailed geography. If not returns only the cost.

UNCOMPACT_GEOMETRY

BOOL

TRUE

If True the full non-compacted geometry between each link in the path. If not return only start and destination nodes of each link in the path.

FALLBACK_WRONG_WAY_SPEED_RATIO

FLOAT64

NULL

Defines the penalty ratio that should be applied to take a one-way road backwards. Value should be between 1 and 0 (excluded). If NULL, one-way roads cannot be used backwards.

MAX_SNAPPING_DISTANCE

FLOAT64

NULL

Defines the maximum allowed snapping distance (in meters) between start and destination points and network nodes. If exceeded no route is returned. If NULL all snapping distance are allowed.

Return type

The output table includes the following columns:

  • start_geo: GEOGRAPHY Start point from source points array.

  • dest_geo: GEOGRAPHY Destination point from destination points array.

  • start_geo_snapped: GEOGRAPHY Start point snapped to the nearest start node of links of the network.

  • dest_geo_snapped: GEOGRAPHY Destination point snapped to the nearest destination node of links of the network.

  • start_order: INT64 Start point position in the source points array.

  • dest_order: INT64 Destination point position in the destination points array.

  • start_s2: INT64 Unique identifier of the start point snapped from start point.

  • dest_s2: INT64 Unique identifier of the destination node snapped from destination point.

  • cost: FLOAT64 Overall cost of the path (travel time or distance depending on the TYPE parameter value).

  • distance: FLOAT64 Overall driving distance of the path in meters.

  • travel_time: FLOAT64 Overall travel time of the path in seconds.

  • path: GEOGRAPHY Overall path.

  • detailed_linestring: RECORD: Array of links that makes up the path.

    • start_s2 INT64: Unique identifier of the start node of the link.

    • dest_s2 INT64: Unique identifier of the destination node of the link.

    • speed: FLOAT64 Speed over the link.

    • cost: FLOAT64 Cost of the link (travel time or distance depending on the TYPE parameter value).

    • distance: FLOAT64 Driving distance of the link in meters.

    • travel_time: FLOAT64 Travel time of the path in seconds.

    • path: GEOGRAPHY Path of the link.

    • detailed_geography: ARRAY<GEOGRAPHY> Array of points that makes up the link.

Example

CALL `carto-un`.carto.ROUTING_MATRIX(
     -- start_point_array
    [ST_GEOGPOINT(-73.0, 40.0),ST_GEOGPOINT(-73.0, 41.0)],
    -- dest_point_array
    [ST_GEOGPOINT(-75.0, 41.0),ST_GEOGPOINT(-75.0, 40.0)],
    -- area of interest,
    ST_GEOGFROMTEXT("FULLGLOBE"),
    -- transportation mode
    'car',
    -- do_network_table
    'cdb_road_networ_81badfc2',
     --do_source
    '<my-dataobs-project>.<my-dataobs-dataset>',
     --output_table
    '<my-project>.<my-dataset>.<output_filename>',
    -- options
    """
    {
       "TYPE":"time",
       "MAX_COST":"100000",
       "WITH_PATH":"True"
    }
    """
);
-- {
--   "start_geo": "POINT(-73 40)",
--   "dest_geo": "POINT(-75 41)",
--   "start_geo_snapped": "POINT(-74.013134 40.688339)",
--   "dest_geo_snapped": "POINT(-74.026365 40.685995)",
--   "start_order": "0",
--   "dest_order": "0",
--   "start_s2": "-8520148151882761037",
--   "dest_s2": "-8520148044108704841",
--   "cost": "1082.6350274098224",
--   "distance": "1397.2114843386769",
--   "travel_time": "1082.6350274098224",
--   "path": "LINESTRING(-74.013134 40.688339, ..., -74.026365 40.685995)",
--   "detailed_linestring": [{
--     "start_s2": "-8520148151882761037",
--     "dest_s2": "-8520148151714079533",
--     "speed": "1.9",
--     "cost": "10.694765667341704",
--     "distance": "20.320054767949237",
--     "travel_time": "10.694765667341704",
--     "path": "LINESTRING(-74.013134 40.688339, -74.013375 40.688339)",
--     "detailed_geography": ["POINT(-74.013134 40.688339)", "POINT(-74.013375 40.688339)"]
--   },
--   ...,
--   {
--     "start_s2": "-8520148151867093047",
--     "dest_s2": "-8520148151854368777",
--     "speed": "1.2",
--     "cost": "11.348771839149197",
--     "distance": "13.618526206979036",
--     "travel_time": "11.348771839149197",
--     "path": "LINESTRING(-74.013587 40.688492, -74.013702 40.688578)",
--     "detailed_geography": ["POINT(-74.013587 40.688492)", "POINT(-74.013702 40.688578)"]
--   }]
-- }, {
--   "start_geo": "POINT(-73 40)",
--   "dest_geo": "POINT(-75 40)",
--   "start_geo_snapped": "POINT(-74.013134 40.688339)",
--   "dest_geo_snapped": "POINT(-74.026041 40.684658)",
--   "start_order": "0",
--   "dest_order": "1",
--   "start_s2": "-8520148151882761037",
--   "dest_s2": "-8520148043684863917",
--   "cost": "1124.4760381433846",
--   "distance": "1248.9194302355879",
--   "travel_time": "1124.4760381433846",
--   "path": "LINESTRING(-74.013134 40.688339, ..., -74.026041 40.684658)",
--   "detailed_linestring": [{
--     "start_s2": "-8520148151882761037",
--     "dest_s2": "-8520148151721556507",
--     "speed": "1.5",
--     "cost": "19.218684425894505",
--     "distance": "28.828026638841756",
--     "travel_time": "19.218684425894505",
--     "path": "LINESTRING(-74.013134 40.688339, -74.013221 40.688225, -74.013358 40.688151)",
--     "detailed_geography": ["POINT(-74.013134 40.688339)", "POINT(-74.013221 40.688225)", "POINT(-74.013358 40.688151)"]
--   },
--   ...,
--   {
--     "start_s2": "-8520148055505489297",
--     "dest_s2": "-8520148043684863917",
--     "speed": "1.0",
--     "cost": "305.40490363182045",
--     "distance": "305.40490363182045",
--     "travel_time": "305.40490363182045",
--     "path": "LINESTRING(-74.022772 40.684401, ..., -74.026041 40.684658)",
--     "detailed_geography": ["POINT(-74.022772 40.684401)", ..., "POINT(-74.026041 40.684658)"]
--   }]
-- },
-- ...
CALL `carto-un-eu`.carto.ROUTING_MATRIX(
     -- start_point_array
    [ST_GEOGPOINT(-73.0, 40.0),ST_GEOGPOINT(-73.0, 41.0)],
    -- dest_point_array
    [ST_GEOGPOINT(-75.0, 41.0),ST_GEOGPOINT(-75.0, 40.0)],
    -- area of interest,
    ST_GEOGFROMTEXT("FULLGLOBE"),
    -- transportation mode
    'car',
    -- do_network_table
    'cdb_road_networ_81badfc2',
     --do_source
    '<my-dataobs-project>.<my-dataobs-dataset>',
     --output_table
    '<my-project>.<my-dataset>.<output_filename>',
    -- options
    """
    {
       "TYPE":"time",
       "MAX_COST":"100000",
       "WITH_PATH":"True"
    }
    """
);
-- {
--   "start_geo": "POINT(-73 40)",
--   "dest_geo": "POINT(-75 41)",
--   "start_geo_snapped": "POINT(-74.013134 40.688339)",
--   "dest_geo_snapped": "POINT(-74.026365 40.685995)",
--   "start_order": "0",
--   "dest_order": "0",
--   "start_s2": "-8520148151882761037",
--   "dest_s2": "-8520148044108704841",
--   "cost": "1082.6350274098224",
--   "distance": "1397.2114843386769",
--   "travel_time": "1082.6350274098224",
--   "path": "LINESTRING(-74.013134 40.688339, ..., -74.026365 40.685995)",
--   "detailed_linestring": [{
--     "start_s2": "-8520148151882761037",
--     "dest_s2": "-8520148151714079533",
--     "speed": "1.9",
--     "cost": "10.694765667341704",
--     "distance": "20.320054767949237",
--     "travel_time": "10.694765667341704",
--     "path": "LINESTRING(-74.013134 40.688339, -74.013375 40.688339)",
--     "detailed_geography": ["POINT(-74.013134 40.688339)", "POINT(-74.013375 40.688339)"]
--   },
--   ...,
--   {
--     "start_s2": "-8520148151867093047",
--     "dest_s2": "-8520148151854368777",
--     "speed": "1.2",
--     "cost": "11.348771839149197",
--     "distance": "13.618526206979036",
--     "travel_time": "11.348771839149197",
--     "path": "LINESTRING(-74.013587 40.688492, -74.013702 40.688578)",
--     "detailed_geography": ["POINT(-74.013587 40.688492)", "POINT(-74.013702 40.688578)"]
--   }]
-- }, {
--   "start_geo": "POINT(-73 40)",
--   "dest_geo": "POINT(-75 40)",
--   "start_geo_snapped": "POINT(-74.013134 40.688339)",
--   "dest_geo_snapped": "POINT(-74.026041 40.684658)",
--   "start_order": "0",
--   "dest_order": "1",
--   "start_s2": "-8520148151882761037",
--   "dest_s2": "-8520148043684863917",
--   "cost": "1124.4760381433846",
--   "distance": "1248.9194302355879",
--   "travel_time": "1124.4760381433846",
--   "path": "LINESTRING(-74.013134 40.688339, ..., -74.026041 40.684658)",
--   "detailed_linestring": [{
--     "start_s2": "-8520148151882761037",
--     "dest_s2": "-8520148151721556507",
--     "speed": "1.5",
--     "cost": "19.218684425894505",
--     "distance": "28.828026638841756",
--     "travel_time": "19.218684425894505",
--     "path": "LINESTRING(-74.013134 40.688339, -74.013221 40.688225, -74.013358 40.688151)",
--     "detailed_geography": ["POINT(-74.013134 40.688339)", "POINT(-74.013221 40.688225)", "POINT(-74.013358 40.688151)"]
--   },
--   ...,
--   {
--     "start_s2": "-8520148055505489297",
--     "dest_s2": "-8520148043684863917",
--     "speed": "1.0",
--     "cost": "305.40490363182045",
--     "distance": "305.40490363182045",
--     "travel_time": "305.40490363182045",
--     "path": "LINESTRING(-74.022772 40.684401, ..., -74.026041 40.684658)",
--     "detailed_geography": ["POINT(-74.022772 40.684401)", ..., "POINT(-74.026041 40.684658)"]
--   }]
-- },
-- ...
CALL carto.ROUTING_MATRIX(
     -- start_point_array
    [ST_GEOGPOINT(-73.0, 40.0),ST_GEOGPOINT(-73.0, 41.0)],
    -- dest_point_array
    [ST_GEOGPOINT(-75.0, 41.0),ST_GEOGPOINT(-75.0, 40.0)],
    -- area of interest,
    ST_GEOGFROMTEXT("FULLGLOBE"),
    -- transportation mode
    'car',
    -- do_network_table
    'cdb_road_networ_81badfc2',
     --do_source
    '<my-dataobs-project>.<my-dataobs-dataset>',
     --output_table
    '<my-project>.<my-dataset>.<output_filename>',
    -- options
    """
    {
       "TYPE":"time",
       "MAX_COST":"100000",
       "WITH_PATH":"True"
    }
    """
);
-- {
--   "start_geo": "POINT(-73 40)",
--   "dest_geo": "POINT(-75 41)",
--   "start_geo_snapped": "POINT(-74.013134 40.688339)",
--   "dest_geo_snapped": "POINT(-74.026365 40.685995)",
--   "start_order": "0",
--   "dest_order": "0",
--   "start_s2": "-8520148151882761037",
--   "dest_s2": "-8520148044108704841",
--   "cost": "1082.6350274098224",
--   "distance": "1397.2114843386769",
--   "travel_time": "1082.6350274098224",
--   "path": "LINESTRING(-74.013134 40.688339, ..., -74.026365 40.685995)",
--   "detailed_linestring": [{
--     "start_s2": "-8520148151882761037",
--     "dest_s2": "-8520148151714079533",
--     "speed": "1.9",
--     "cost": "10.694765667341704",
--     "distance": "20.320054767949237",
--     "travel_time": "10.694765667341704",
--     "path": "LINESTRING(-74.013134 40.688339, -74.013375 40.688339)",
--     "detailed_geography": ["POINT(-74.013134 40.688339)", "POINT(-74.013375 40.688339)"]
--   },
--   ...,
--   {
--     "start_s2": "-8520148151867093047",
--     "dest_s2": "-8520148151854368777",
--     "speed": "1.2",
--     "cost": "11.348771839149197",
--     "distance": "13.618526206979036",
--     "travel_time": "11.348771839149197",
--     "path": "LINESTRING(-74.013587 40.688492, -74.013702 40.688578)",
--     "detailed_geography": ["POINT(-74.013587 40.688492)", "POINT(-74.013702 40.688578)"]
--   }]
-- }, {
--   "start_geo": "POINT(-73 40)",
--   "dest_geo": "POINT(-75 40)",
--   "start_geo_snapped": "POINT(-74.013134 40.688339)",
--   "dest_geo_snapped": "POINT(-74.026041 40.684658)",
--   "start_order": "0",
--   "dest_order": "1",
--   "start_s2": "-8520148151882761037",
--   "dest_s2": "-8520148043684863917",
--   "cost": "1124.4760381433846",
--   "distance": "1248.9194302355879",
--   "travel_time": "1124.4760381433846",
--   "path": "LINESTRING(-74.013134 40.688339, ..., -74.026041 40.684658)",
--   "detailed_linestring": [{
--     "start_s2": "-8520148151882761037",
--     "dest_s2": "-8520148151721556507",
--     "speed": "1.5",
--     "cost": "19.218684425894505",
--     "distance": "28.828026638841756",
--     "travel_time": "19.218684425894505",
--     "path": "LINESTRING(-74.013134 40.688339, -74.013221 40.688225, -74.013358 40.688151)",
--     "detailed_geography": ["POINT(-74.013134 40.688339)", "POINT(-74.013221 40.688225)", "POINT(-74.013358 40.688151)"]
--   },
--   ...,
--   {
--     "start_s2": "-8520148055505489297",
--     "dest_s2": "-8520148043684863917",
--     "speed": "1.0",
--     "cost": "305.40490363182045",
--     "distance": "305.40490363182045",
--     "travel_time": "305.40490363182045",
--     "path": "LINESTRING(-74.022772 40.684401, ..., -74.026041 40.684658)",
--     "detailed_geography": ["POINT(-74.022772 40.684401)", ..., "POINT(-74.026041 40.684658)"]
--   }]
-- },
-- ...

Limitations

Since this module runs natively on Bigquery, it relies exclusively on the resources allocated by the data warehouse for the query.

If a request fails due to a resource limit, you can try the following:

  • reduce the size of the network (reduce the size of the area of interest)

  • reduce or split into different queries the points in start_point_array

  • set or reduce (if it already exists) the MAX_COST parameter

  • set WITH_PATH parameter to False

In some cases road networks contain segments that are not connected to the main network. If any of the destination or origin points are closer to such segments than to other parts of the network it won't be possible to find routes to or from such points and some paths can be missing from the results. We're working on improving the quality of the road networks to avoid such problems. If you find this problem using the car transportation mode you can try using car_major_road_only or car_motorway_only instead, since the major roads network is less prone to this kind of problem.

ROUTING_ISOLINES

ROUTING_ISOLINES(start_point_array, cost_limit_array, area_of_interest, transportation_mode, do_network_table, do_source, output_table, options)

Description

This procedure generates a table containing isolines in terms of either travel times (isochrones) or distances (isodistances) for a given set of origin locations and range limits to be computed on the road network table.

  • start_point_array: ARRAY<GEOGRAPHY> Source points array. The node of the network nearest to this point will be used as the source point to compute the shortest path.

  • cost_limit_array: ARRAY<FLOAT64> Cost limit array. For each cost limit all the path within this range are returned. For an isochrone the cost is time in seconds, for an isodistance it's distance in meters.

  • area_of_interest: GEOGRAPHY Area of interest over where the analysis takes place.

  • transportation_mode: STRING Type of transportation mode to be used for the calculation of isolines. Available options: car, car_motorway_only, car_major_road_only, bicycle or foot.

  • do_network_table: STRING Identifier (slug) of the Data Observatory Network table.

  • do_source: STRING Name of the location where the Data Observatory subscriptions of the user are stored, in <my-dataobs-project>.<my-dataobs-dataset> format. If only the <my-dataobs-dataset> is included, it uses the project carto-data by default. It can be set to NULL or ''.

  • output_table: STRING The full path name of the output table.

  • options: STRING Containing a valid JSON with the different options. Valid options are described the table below. If options is set to NULL the all options are set to default.

Option
Type
Default
Description

TYPE

STRING

time

Defines the kind of optimisation for pathfinding. Possible values: "time", "distance".

UNCOMPACT_GEOMETRY

BOOL

TRUE

If True the full non-compacted geometry between each link in the path. If not return only start and destination nodes of each link in the path.

FALLBACK_WRONG_WAY_SPEED_RATIO

FLOAT64

NULL

Defines the penalty ratio that should be applied to take a one-way road backward. Value should be between 1 and 0 (excluded). If NULL, one-way road cannot be used backward.

MAX_SNAPPING_DISTANCE

FLOAT64

NULL

Defines maximum allowed snapping distance (in meters) between start and destination points and network nodes. If exceeded no route is returned. If NULL all snapping distance are allowed.

Return type

The output table includes the following columns:

  • cost_limit: FLOAT64 Cost limit from the start_point_array input parameter taken in account for this row.

  • cost_limit_idx: INT64 Cost limit position from the start_point_array input parameter taken in account for this row.

  • start_order: INT64 Start point position from the source points array taken in account for this row.

  • start_geo: GEOGRAPHY The point geometry of the starting node taken in account for this row.

  • start_geo_snapped: GEOGRAPHY Start point snapped to the nearest start node of links of the network.

  • start_s2: INT64 Index of the node snapped from start point.

  • start_cost: FLOAT64 Cost from snapped start point to the start node of the link.

  • dest_s2: INT64 The unique identifier of the destination node of the link.

  • dest_cost: FLOAT64 Cost from snapped start point to the destination node of the link.

  • detailed_geography: ARRAY<GEOGRAPHY> Array of points that makes up the link.

  • detailed_geography_chunked_agg: GEOGRAPHY Link geography chunked to cost limit and aggregated in a single geography.

Example

CALL `carto-un`.carto.ROUTING_ISOLINES(
   -- start_point_array
    [ST_GEOGPOINT(-73.0, 40.0)],
    -- cost_limit_array
    [60., 120.],
    -- area of interest,
    ST_GEOGFROMTEXT("FULLGLOBE"),
    -- transportation mode
    'car',
    -- do_network_table
    'cdb_road_networ_81badfc2',
     --do_source
    '<my-dataobs-project>.<my-dataobs-dataset>',
    --output_table
    '<my-project>.<my-dataset>.<output_filename>',
   -- options
   """
   {
      "TYPE":"time",
      "MAX_COST":"100000",
      "WITH_PATH":"False"
   }
   """
);

-- {
--   "start_geo": "POINT(-122.3296557 47.582691)",
--   "dest_geo": "POINT(-122.3290612 47.5807722)",
--   "start_geo_snapped": "POINT(-122.3296557 47.582691)",
--   "dest_geo_snapped": "POINT(-122.3290612 47.5807722)",
--   "start_order": "0",
--   "dest_order": "35164",
--   "start_s2": "6093487519859207645",
--   "dest_s2": "6093440836742041863",
--   "cost": "27.095695089725034",
--   "distance": "309.31565973502575",
--   "travel_time": "27.095695089725034",
--   "path": "LINESTRING(-122.3296557 47.582691, -122.3298669 47.5827281, ..., -122.3290612 47.5807722)",
--   "detailed_linestring": [{
--     "start_s2": "6093487519859207645",
--     "dest_s2": "6093440836214032467",
--     "speed": "4.166666666666667",
--     "cost": "5.8301084779070846",
--     "distance": "24.292118657946187",
--     "travel_time": "5.8301084779070846",
--     "path": "LINESTRING(-122.3296557 47.582691, -122.3298669 47.5827281, -122.3299725 47.5827299)",
--     "detailed_geography": ["POINT(-122.3296557 47.582691)", "POINT(-122.3298669 47.5827281)", "POINT(-122.3299725 47.5827299)"]
--   },
--   ...,
--   {
--     "start_s2": "6093440836753434943",
--     "dest_s2": "6093440836742041863",
--     "speed": "18.055555555555554",
--     "cost": "0.658359285678671",
--     "distance": "11.887042658087113",
--     "travel_time": "0.658359285678671",
--     "path": "LINESTRING(-122.3290623 47.5808791, -122.3290612 47.5807722)",
--     "detailed_geography": ["POINT(-122.3290623 47.5808791)", "POINT(-122.3290612 47.5807722)"]
--   }]
-- }, ...
CALL `carto-un-eu`.carto.ROUTING_ISOLINES(
   -- start_point_array
    [ST_GEOGPOINT(-73.0, 40.0)],
    -- cost_limit_array
    [60., 120.],
    -- area of interest,
    ST_GEOGFROMTEXT("FULLGLOBE"),
    -- transportation mode
    'car',
    -- do_network_table
    'cdb_road_networ_81badfc2',
     --do_source
    '<my-dataobs-project>.<my-dataobs-dataset>',
    --output_table
    '<my-project>.<my-dataset>.<output_filename>',
   -- options
   """
   {
      "TYPE":"time",
      "MAX_COST":"100000",
      "WITH_PATH":"False"
   }
   """
);

-- {
--   "start_geo": "POINT(-122.3296557 47.582691)",
--   "dest_geo": "POINT(-122.3290612 47.5807722)",
--   "start_geo_snapped": "POINT(-122.3296557 47.582691)",
--   "dest_geo_snapped": "POINT(-122.3290612 47.5807722)",
--   "start_order": "0",
--   "dest_order": "35164",
--   "start_s2": "6093487519859207645",
--   "dest_s2": "6093440836742041863",
--   "cost": "27.095695089725034",
--   "distance": "309.31565973502575",
--   "travel_time": "27.095695089725034",
--   "path": "LINESTRING(-122.3296557 47.582691, -122.3298669 47.5827281, ..., -122.3290612 47.5807722)",
--   "detailed_linestring": [{
--     "start_s2": "6093487519859207645",
--     "dest_s2": "6093440836214032467",
--     "speed": "4.166666666666667",
--     "cost": "5.8301084779070846",
--     "distance": "24.292118657946187",
--     "travel_time": "5.8301084779070846",
--     "path": "LINESTRING(-122.3296557 47.582691, -122.3298669 47.5827281, -122.3299725 47.5827299)",
--     "detailed_geography": ["POINT(-122.3296557 47.582691)", "POINT(-122.3298669 47.5827281)", "POINT(-122.3299725 47.5827299)"]
--   },
--   ...,
--   {
--     "start_s2": "6093440836753434943",
--     "dest_s2": "6093440836742041863",
--     "speed": "18.055555555555554",
--     "cost": "0.658359285678671",
--     "distance": "11.887042658087113",
--     "travel_time": "0.658359285678671",
--     "path": "LINESTRING(-122.3290623 47.5808791, -122.3290612 47.5807722)",
--     "detailed_geography": ["POINT(-122.3290623 47.5808791)", "POINT(-122.3290612 47.5807722)"]
--   }]
-- }, ...
CALL carto.ROUTING_ISOLINES(
   -- start_point_array
    [ST_GEOGPOINT(-73.0, 40.0)],
    -- cost_limit_array
    [60., 120.],
    -- area of interest,
    ST_GEOGFROMTEXT("FULLGLOBE"),
    -- transportation mode
    'car',
    -- do_network_table
    'cdb_road_networ_81badfc2',
     --do_source
    '<my-dataobs-project>.<my-dataobs-dataset>',
    --output_table
    '<my-project>.<my-dataset>.<output_filename>',
   -- options
   """
   {
      "TYPE":"time",
      "MAX_COST":"100000",
      "WITH_PATH":"False"
   }
   """
);

-- {
--   "start_geo": "POINT(-122.3296557 47.582691)",
--   "dest_geo": "POINT(-122.3290612 47.5807722)",
--   "start_geo_snapped": "POINT(-122.3296557 47.582691)",
--   "dest_geo_snapped": "POINT(-122.3290612 47.5807722)",
--   "start_order": "0",
--   "dest_order": "35164",
--   "start_s2": "6093487519859207645",
--   "dest_s2": "6093440836742041863",
--   "cost": "27.095695089725034",
--   "distance": "309.31565973502575",
--   "travel_time": "27.095695089725034",
--   "path": "LINESTRING(-122.3296557 47.582691, -122.3298669 47.5827281, ..., -122.3290612 47.5807722)",
--   "detailed_linestring": [{
--     "start_s2": "6093487519859207645",
--     "dest_s2": "6093440836214032467",
--     "speed": "4.166666666666667",
--     "cost": "5.8301084779070846",
--     "distance": "24.292118657946187",
--     "travel_time": "5.8301084779070846",
--     "path": "LINESTRING(-122.3296557 47.582691, -122.3298669 47.5827281, -122.3299725 47.5827299)",
--     "detailed_geography": ["POINT(-122.3296557 47.582691)", "POINT(-122.3298669 47.5827281)", "POINT(-122.3299725 47.5827299)"]
--   },
--   ...,
--   {
--     "start_s2": "6093440836753434943",
--     "dest_s2": "6093440836742041863",
--     "speed": "18.055555555555554",
--     "cost": "0.658359285678671",
--     "distance": "11.887042658087113",
--     "travel_time": "0.658359285678671",
--     "path": "LINESTRING(-122.3290623 47.5808791, -122.3290612 47.5807722)",
--     "detailed_geography": ["POINT(-122.3290623 47.5808791)", "POINT(-122.3290612 47.5807722)"]
--   }]
-- }, ...

The output table returns links that form the isolines indexed by origin location and range limits. To get the full isoline geographies you need to aggregate the table:

SELECT ST_UNION_AGG(detailed_geography_chunked_agg) AS full_isoline_geography
FROM `output_table`
GROUP BY cost_limit, start_s2
SELECT ST_UNION_AGG(detailed_geography_chunked_agg) AS full_isoline_geography
FROM `output_table`
GROUP BY cost_limit, start_s2
SELECT ST_UNION_AGG(detailed_geography_chunked_agg) AS full_isoline_geography
FROM `output_table`
GROUP BY cost_limit, start_s2

Limitations

Since this module runs natively on Bigquery, it relies exclusively on the resources allocated by the data warehouse for the query.

If a request fails due to a resource limit, you can try the following:

  • reduce the size of the network (reduce the size of the area of interest)

  • reduce or split into different queries the points in start_point_array

  • reduce the maximum the cost limit in cost_limit_array

In some cases road networks contain segments that are not connected to the main network. If any of the destination or origin points are closer to such segments than to other parts of the network it won't be possible to find routes to or from such points and some paths can be missing from the results. We're working on improving the quality of the road networks to avoid such problems. If you find this problem using the car transportation mode you can try using car_major_road_only or car_motorway_only instead, since the major roads network is less prone to this kind of problem.

This project has received funding from the research and innovation programme under grant agreement No 960401.

road network
this guide
European Union’s Horizon 2020