Vantage Geo Distance Logic Documentation

Overview

The geoDistance logic in Vantage calculates the distance between two geographic points specified by their latitude and longitude coordinates. It employs the Haversine formula, which computes distances on the surface of a sphere, making it well-suited for geographical calculations. This logic does not depend on external APIs, ensuring its operations are self-contained and efficient.

Purpose

The main function of this logic is to enable users to derive the distance between two sets of geographic coordinates for various analytical needs, such as:

• Distance calculations for logistics and route planning.
• Geospatial analysis in spatial data applications.
• Enhancing location-based services and recommendations.

Settings

1. Latitude 1 Column (lat1Column)

• Input Type: Text (string)
• Description: Specifies the column name in the input data that contains the latitude of the first point. It must have numeric values formatted as strings (e.g., "34.0522").
• Default Value: '' (empty string)

2. Longitude 1 Column (lng1Column)

• Input Type: Text (string)
• Description: Specifies the column name in the input data for the longitude of the first point. Similar to latitude, it must have numeric values formatted as strings (e.g., "-118.2437").
• Default Value: '' (empty string)

3. Latitude 2 Column (lat2Column)

• Input Type: Text (string)
• Description: Indicates the column name that contains the latitude of the second point. The value should be in the same format as for the first latitude.
• Default Value: '' (empty string)

4. Longitude 2 Column (lng2Column)

• Input Type: Text (string)
• Description: Specifies the column name for the longitude of the second point, also requiring numeric values formatted as strings.
• Default Value: '' (empty string)

5. Output Column Name (outputColumn)

• Input Type: Text (string)
• Description: Defines the name of the new column in the output data that will hold the computed distance. Users can customize this to fit their schema.
• Default Value: 'distance'

6. Unit (unit)

• Input Type: Dropdown (selection)

• Description: Allows the user to choose the measurement unit for the distance. Options include:

  • km (kilometers)
  • miles

  Changing this setting alters the unit of the computed distance. Selecting miles will convert the distance calculated in kilometers.

• Default Value: 'km'

I/O Ports

• Input Ports:

  • data_in: Accepts input data of type data, which may be in the form of an array or an object.

• Output Ports:

  • data_out: Outputs data of type data, returning an array that includes the original data along with the computed distance.

How It Works

The geoDistance logic executes the following steps:

1. It retrieves the configuration values provided by the user for both the latitudes and longitudes of the two points.
2. It processes the input data, extracting the latitude and longitude values from the specified columns.
3. Using the Haversine formula, it calculates the distance between the specified geographic points.
4. Depending on the user's choice of units, the distance is converted accordingly (to miles if specified).
5. The calculated distance is added to each row in the output data under the provided output column name, which defaults to 'distance'.

Data Expectations

• Input Data: The logic expects a structured input data type, either as an array of objects (where each object represents a row of data) or as a single object. Each object must include the columns defined by lat1Column, lng1Column, lat2Column, and lng2Column, containing valid numeric string representations of latitude and longitude.
• Output Data: The output will consist of the original input data with an additional column specified by outputColumn, containing the computed distances between the coordinate pairs.

Use Cases & Examples

Use Cases

1. Logistics and Route Optimization: A delivery service can use the geoDistance logic to compute distances between various delivery points to optimize routes, reducing fuel costs and delivery times.

2. Real Estate Analytics: A real estate platform can utilize this logic to calculate the distance from properties to key locations (schools, parks, shops) to provide valuable data to potential buyers.

3. Location-Based Marketing: A marketing platform can employ this logic to target customers based on their proximity to retail stores or events, enhancing promotional strategies.

Example Configuration

Use Case: Delivery Service Route Optimization

Scenario: A delivery service needs to calculate distances from their depot to various delivery locations.

Sample Input Data:

[
    {"location": "Customer A", "lat1": "34.0522", "lng1": "-118.2437", "lat2": "34.0520", "lng2": "-118.2500"},
    {"location": "Customer B", "lat1": "34.0522", "lng1": "-118.2437", "lat2": "34.0600", "lng2": "-118.2400"}
]

Sample Configuration:

{
    "lat1Column": "lat1",
    "lng1Column": "lng1",
    "lat2Column": "lat2",
    "lng2Column": "lng2",
    "outputColumn": "distanceToCustomer",
    "unit": "km"
}

Expected Output:

[
    {"location": "Customer A", "lat1": "34.0522", "lng1": "-118.2437", "lat2": "34.0520", "lng2": "-118.2500", "distanceToCustomer": 1.42},
    {"location": "Customer B", "lat1": "34.0522", "lng1": "-118.2437", "lat2": "34.0600", "lng2": "-118.2400", "distanceToCustomer": 0.86}
]

AI Integrations

While the geoDistance logic currently operates independently of AI integrations, it can be beneficial in conjunction with machine learning models that predict or optimize routes based on distance metrics. By providing precise distance calculations, this logic can enhance predictive analytics and decision-making processes in various applications.

Billing Impacts

Since the geoDistance logic performs calculations without relying on external services, it does not incur any additional API usage fees. The billing would be limited to the costs associated with the data processing capabilities of the Vantage platform. However, heavier usage (processing larger datasets) may influence pricing based on the usage tier of the Vantage service plan.