Simple Distance Matrix Example

Explore the NextBillion.ai Distance Matrix API in both Flex and Standard modes with our Technical Notebook. In this technical notebook, we dissect a simple distance matrix example in both Flexible and Standard (Fast) modes using the NextBillion.ai Distance Matrix API. 

Distance Matrix API enables you to calculate distances and estimated time of arrivals (ETAs) across various scenarios—whether it’s a one-to-many or many-to-many configuration. The API delivers a matrix of ETAs and distances, providing a comprehensive overview of each unique origin and destination pairing.

Understanding the Matrix

Picture this: You have a set of origins {A, B} and destinations {C, D, E}. The API seamlessly provides a matrix of results, furnishing distances (in meters) and times (in seconds) for each pairing. The matrix looks like this:

 

C

D

E

A

A → C

A → D

A → E

B

B → C

B → D

B → E

NextBillion.ai’s Distance Matrix API has two versions – Fast (Standard) and Flexible. Let’s explore these two versions.

Distance Matrix Fast (Standard) API

The Fast API delivers real-time ETAs and distances, factoring in typical traffic conditions at the time of the request.

The Fast mode of the Distance Matrix API is your go-to choice for real-time efficiency, providing instantaneous Estimated Times of Arrival (ETAs) and distances, all while factoring in the prevailing traffic conditions. Let’s explore some real-life use cases where the Fast mode shines:

Urban Delivery Logistics

Imagine a fleet of delivery vehicles navigating through a bustling city. The Fast mode ensures that these vehicles receive the most up-to-date ETAs, considering the dynamic nature of urban traffic. This is critical for optimizing delivery routes, meeting customer expectations, and enhancing overall logistics efficiency.

Emergency Services Routing

For emergency services like ambulances or fire trucks, every second counts. The Fast mode equips these services with the ability to dynamically adjust routes based on real-time traffic, ensuring swift and efficient responses to emergencies. This can be a crucial factor in saving lives and mitigating the impact of unforeseen incidents.

Ride-Hailing Optimization

In the world of ride-hailing services, the Fast mode becomes indispensable. It enables platforms to provide accurate arrival times to users, taking into account the current traffic conditions. This not only improves the user experience but also aids drivers in optimizing their routes for quicker pickups and drop-offs.

Distance Matrix Flexible API

The Flexible version introduces additional parameters, allowing consideration of truck-specific routes, specific departure times, and preference for the `fastest` or `shortest` route. 

The Flexible mode of the Distance Matrix API introduces a layer of customization, allowing you to tailor your routing requests to specific requirements. Here are some real-life scenarios where the Flexible mode proves its versatility:

Truck-Specific Routing for Logistics

In the logistics industry, especially for transporting goods using trucks, the Flexible mode comes into play. It considers parameters like truck dimensions and weight, providing routes that adhere to truck-specific restrictions. This ensures that logistics companies can plan routes that are not only efficient but also compliant with the unique constraints of truck transportation.

Time-Sensitive Deliveries

For businesses involved in time-sensitive deliveries, such as perishable goods or time-critical shipments, the Flexible mode allows users to specify departure times. This ensures that ETAs are calculated based on the typical traffic conditions at the given start time, enabling more accurate planning for time-sensitive deliveries.

Customized Routing Preferences

Different scenarios may demand different routing preferences. The Flexible mode lets users choose between the ‘fastest’ and ‘shortest’ route types based on their specific needs. This flexibility is valuable for applications ranging from daily commutes to strategic business operations, allowing users to prioritize speed or efficiency as required.

The Fast (Standard) and Flexible modes cater to distinct needs in various real-life scenarios. While Fast mode excels in providing quick and real-time routing information, Flexible mode steps in when customization and detailed parameters are paramount. Whether you’re optimizing urban logistics, responding to emergencies, or fine-tuning truck routes, NextBillion.ai’s Distance Matrix API has you covered.

Implementation Steps

The notebook implements the following steps to utilize the Distance Matrix API. 

1. API Key Setup

Contact [email protected] to get your API key.

Acquire your API key and initialize it with the provided code snippet.

nextbillion.setApiKey(your_api_key);

2. Stylesheet Integration

The following link integrates the NB.ai SDK stylesheet to your project:

link href="https://maps-gl.nextbillion.io/maps/v2/api/css" rel="stylesheet"

3. Address Configuration

Tailor the input addresses to your preference, modifying the array as needed. This notebook example showcases the following airport locations in and around Los Angeles.

addresses = Array(7) [
 0: "Los Angeles International Airport, Los Angeles, CA"
 1: "Orange Country International Airport, Santa Ana, CA"
 2: "San Diego International Airport, San Diego, CA"
 3: "Burbank Airport, Burbank, CA"
 4: "Long Beach, CA"
 5: "Riverside, CA"
 6: "Rancho Palos Verdes"
]

4. Geocoding Addresses

The Geocode algorithm converts all input addresses to fetch latitude and longitude pairs for each location.

5. Distance Matrix Request

In this step, a balanced distance matrix request is set up between each point using geocode addresses. 

Set up the following parameters as per your desired use case: 

  • Departure Time: Specify the designated time for departure.
  • Route Profile: Designate the route profile as either `Automobile` or `Truck`.
  • Options: Choose between `Standard` or `Flexible` options.

The tool returns a distance matrix in a formatted table showcasing travel time in minutes and travel distance in kilometers between each location along with a visual representation. Click on individual cells to view the route.

Let’s take a look at examples in both standard and flexible modes. 

Example 1: Standard(Fast) Mode

In this example, we set the parameters to the following values.

  • Departure Time: 05/12/2023, 11:30 AM
  • Route Profile: Automobile
  • Options: Standard

The following distance matrix is obtained as a result.

Example 1- Distance Matrix

The following image visualizes the route of the highlighted cell.

Example 2: Flexible Mode

In this example, we set the parameters to the following values.

  • Departure Time: 05/12/2023, 11:30 AM
  • Route Profile: Truck
  • Options: Flexible

The following distance matrix is obtained as a result.

The following image visualizes the route of the highlighted cell.

Refer to NextBillion.ai’s Distance Matrix API documentation for more details.

Access Notebook