### Install RanCoord Package

Source: https://github.com/hugodscarvalho/rancoord/blob/main/README.md

Install the latest version of the RanCoord package using pip. This is the first step to using the library.

```sh
pip install rancoord
```

--------------------------------

### Get a polygon from an address using Python

Source: https://github.com/hugodscarvalho/rancoord/blob/main/README.md

Uses the Nominatim geocoder to retrieve a bounding box for a location and converts it into a polygon.

```python
# Get the bounding box
bounding_box = nominatim_geocoder('Braga, Portugal')
# Create a polygon based on the previously created bounding box
poly = polygon_from_boundingbox(bounding_box)
```

--------------------------------

### Import RanCoord Package

Source: https://github.com/hugodscarvalho/rancoord/blob/main/README.md

Import the rancoord package into your Python script to start using its functionalities. This is a standard import statement.

```python
import rancoord as rc
```

--------------------------------

### Manage Directories

Source: https://context7.com/hugodscarvalho/rancoord/llms.txt

Utility to create directories safely if they do not exist.

```python
import rancoord as rc

# Create a custom directory for outputs
rc.create_dir('my_output_folder')

# Create nested directories
rc.create_dir('results/maps')
rc.create_dir('results/coordinates')

# Directory is only created if it doesn't exist
# No error is raised if directory already exists
```

--------------------------------

### Create a directory using create_dir

Source: https://github.com/hugodscarvalho/rancoord/blob/main/README.md

Creates a new directory if it does not already exist.

```python
dir_name = 'example'

create_dir(dir_name)
```

--------------------------------

### Git workflow for contributing

Source: https://github.com/hugodscarvalho/rancoord/blob/main/README.md

Standard git commands for creating a feature branch and submitting changes.

```bash
git checkout -b feature/AmazingFeature
```

```bash
git commit -m 'Add some AmazingFeature'
```

```bash
git push origin feature/AmazingFeature
```

--------------------------------

### Geocode Address to Polygon

Source: https://context7.com/hugodscarvalho/rancoord/llms.txt

Demonstrates the initial steps of a workflow: geocoding an address and generating a polygon.

```python
import rancoord as rc

# Step 1: Get polygon from an address
bounding_box = rc.nominatim_geocoder('Braga, Portugal')
polygon = rc.polygon_from_boundingbox(bounding_box)
```

--------------------------------

### create_dir(dir_name)

Source: https://github.com/hugodscarvalho/rancoord/blob/main/README.md

Utility function to create a new directory if it does not already exist.

```APIDOC
## create_dir(dir_name)

### Description
Auxiliar function to create a new directory if it doesn't already exists.

### Parameters
- **dir_name** (String) - Optional - Address the new name. Defaults to 'data'.

### Request Example
```python
dir_name = 'example'
create_dir(dir_name)
```
```

--------------------------------

### Create polygons with polygon_from_boundingbox

Source: https://context7.com/hugodscarvalho/rancoord/llms.txt

Convert a list of four bounding box coordinates into a Shapely Polygon object.

```python
import rancoord as rc

# Bounding box from nominatim_geocoder or manually defined
# Format: [min_lat, max_lat, min_lon, max_lon]
bounding_box = ['40.9', '41.5', '-8.8', '-8.4']

# Create polygon from bounding box
polygon = rc.polygon_from_boundingbox(bounding_box)

# Use the polygon for coordinate generation
lat, lon, _ = rc.coordinates_randomizer(polygon=polygon, num_locations=15)
print(f"Generated coordinates within the bounding box polygon")
```

--------------------------------

### polygon_from_boundingbox(boundingbox)

Source: https://github.com/hugodscarvalho/rancoord/blob/main/README.md

Creates a polygon object from a provided bounding box list.

```APIDOC
## polygon_from_boundingbox(boundingbox)

### Description
Function to create a polygon from a bounding box.

### Parameters
- **boundingbox** (List) - Required - List of coordinates of the bounding box.

### Response
- **Returns** (Polygon) - Polygon created from the bounding box.

### Request Example
```python
poly = polygon_from_boundingbox(boundingbox = bounding_box)
```
```

--------------------------------

### Plot Coordinates on Map

Source: https://context7.com/hugodscarvalho/rancoord/llms.txt

Create an interactive Folium map with markers for a list of coordinates.

```python
import rancoord as rc

# Sample coordinates
lat = [41.15, 41.20, 41.25, 41.30, 41.35]
lon = [-8.60, -8.55, -8.50, -8.45, -8.40]

# Plot coordinates on a Folium map
# save=True saves to /maps/map_DDMMYYYY_HHMMSS.html
map_object = rc.plot_coordinates(
    lat=lat,
    lon=lon,
    zoom=11,
    save=True
)

# The map object can be displayed in Jupyter notebooks
# or saved manually with custom names
# map_object.save('custom_map_name.html')
print("Map saved to /maps directory")
```

--------------------------------

### Export Coordinates to Files

Source: https://context7.com/hugodscarvalho/rancoord/llms.txt

Save coordinate lists to JSON, CSV, or Excel formats with automatic timestamping.

```python
import rancoord as rc

# Sample coordinates
lat = [41.15, 41.20, 41.25]
lon = [-8.60, -8.55, -8.50]

# Save as JSON (default)
rc.multiple_formats_saver(
    lat=lat,
    lon=lon,
    columns=['Latitude', 'Longitude'],
    file_format='json',
    file_name='my_coordinates',
    dir_name='output'
)
# Creates: output/my_coordinates_DDMMYYYY_HHMMSS.json

# Save as CSV
rc.multiple_formats_saver(
    lat=lat,
    lon=lon,
    file_format='csv',
    file_name='coords',
    dir_name='exports'
)
# Creates: exports/coords_DDMMYYYY_HHMMSS.csv

# Save as Excel
rc.multiple_formats_saver(
    lat=lat,
    lon=lon,
    file_format='xlsx',
    file_name='locations',
    dir_name='data'
)
# Creates: data/locations_DDMMYYYY_HHMMSS.xlsx
```

--------------------------------

### Export Coordinates in Multiple Formats

Source: https://context7.com/hugodscarvalho/rancoord/llms.txt

Saves the generated latitude and longitude coordinates to a file in a specified format (e.g., CSV) and with a given file name and directory.

```python
rc.multiple_formats_saver(
    lat=lat,
    lon=lon,
    file_format='csv',
    file_name='braga_locations',
    dir_name='vehicle_routing_data'
)
```

--------------------------------

### Analyze Generated Coordinates and Distances

Source: https://context7.com/hugodscarvalho/rancoord/llms.txt

Prints the number of generated coordinates and statistics about the computed distance matrix, including its shape, maximum distance, and average distance between points.

```python
print(f"Generated {len(lat)} coordinates")
print(f"Distance matrix shape: {dist_matrix.shape}")
print(f"Max distance between points: {dist_matrix.max():.2f} km")
print(f"Average distance: {dist_matrix[dist_matrix > 0].mean():.2f} km")
```

--------------------------------

### Calculate Point-to-Point Distances

Source: https://context7.com/hugodscarvalho/rancoord/llms.txt

Calculates and prints the driving distance (using OSRM) and straight-line distance (using Vincenty's formulae) between consecutive points in the generated coordinate list. This loop iterates through the first few pairs of points.

```python
for i in range(min(3, len(lat)-1)):
    osrm_dist = rc.osrm_distance(lat[i], lon[i], lat[i+1], lon[i+1])
    vincenty_dist = rc.vincenty_distance(lat[i], lon[i], lat[i+1], lon[i+1])
    print(f"Point {i} to {i+1}: {osrm_dist} km (driving), {vincenty_dist} km (straight)")
```

--------------------------------

### Save coordinates to file with multiple_formats_saver

Source: https://github.com/hugodscarvalho/rancoord/blob/main/README.md

Saves latitude and longitude lists to a specified file format. Ensure input lists have equal lengths and required directory/file names are provided.

```python
multiple_formats_saver(lat = lat, lon = lon, columns = ['Latitude', 'Longitude'], file_format = 'json', file_name = 'coordinates', dir_name = 'coordinates')
```

--------------------------------

### Generate Distance Matrices

Source: https://context7.com/hugodscarvalho/rancoord/llms.txt

Compute a matrix of distances between coordinate pairs using Vincenty, Haversine, or OSRM methods.

```python
import rancoord as rc
import numpy as np

# Generate some random coordinates first
lat = [41.15, 41.20, 41.25, 41.30]
lon = [-8.60, -8.55, -8.50, -8.45]

# Calculate distance matrix using Vincenty formula (default)
matrix_vincenty = rc.distance_matrix(lat=lat, lon=lon, method='vincenty')
print("Vincenty Distance Matrix (km):")
print(matrix_vincenty)

# Calculate using Haversine formula
matrix_haversine = rc.distance_matrix(lat=lat, lon=lon, method='haversine')
print("\nHaversine Distance Matrix (km):")
print(matrix_haversine)

# Calculate using OSRM (driving distances - requires internet)
matrix_osrm = rc.distance_matrix(lat=lat, lon=lon, method='osrm')
print("\nOSRM Driving Distance Matrix (km):")
print(matrix_osrm)
```

--------------------------------

### Create a polygon from a bounding box

Source: https://github.com/hugodscarvalho/rancoord/blob/main/README.md

Converts a list of bounding box coordinates into a polygon object.

```python

poly = polygon_from_boundingbox(boundingbox = bounding_box)

```

--------------------------------

### Generate random coordinates with coordinates_randomizer

Source: https://context7.com/hugodscarvalho/rancoord/llms.txt

Generate random geographic points within a defined polygon and optionally compute distance matrices or export results.

```python
from shapely.geometry import Polygon
import rancoord as rc

# Define a custom polygon (or use the default Lisbon polygon)
custom_polygon = Polygon([
    (41.1, -8.7),
    (41.1, -8.5),
    (41.2, -8.5),
    (41.2, -8.7)
])

# Generate 50 random coordinates within the polygon
# plot=True saves an interactive HTML map to /maps folder
# save=True exports coordinates to /coordinates folder
# matrix=True computes distance matrix between all points
lat, lon, distance_matrix = rc.coordinates_randomizer(
    polygon=custom_polygon,
    num_locations=50,
    plot=True,
    save=True,
    matrix=True
)

# Output: lat and lon are lists of 50 coordinates each
# distance_matrix is a 50x50 numpy array of distances
print(f"Generated {len(lat)} locations")
print(f"First coordinate: ({lat[0]}, {lon[0]})")
print(f"Distance matrix shape: {distance_matrix.shape}")
```

--------------------------------

### Calculate Straight-Line Distances

Source: https://context7.com/hugodscarvalho/rancoord/llms.txt

Compare Vincenty and Haversine distance calculations for specific coordinate pairs.

```python
distance = rc.vincenty_distance(
    pickup_lat=41.4781,
    pickup_long=-8.1992,
    dropoff_lat=40.8761,
    dropoff_long=-9.1222,
    miles=False
)

print(f"Vincenty distance: {distance} km")

# Compare with Haversine for the same points
haversine_dist = rc.haversine_distance(
    pickup_lat=41.4781,
    pickup_long=-8.1992,
    dropoff_lat=40.8761,
    dropoff_long=-9.1222
)
print(f"Haversine distance: {haversine_dist} km")
```

--------------------------------

### polygon_from_boundingbox

Source: https://context7.com/hugodscarvalho/rancoord/llms.txt

Converts a bounding box, represented as a list of four coordinates, into a Shapely Polygon object.

```APIDOC
## POST /polygon_from_boundingbox

### Description
Converts a bounding box into a Shapely Polygon object.

### Method
POST

### Endpoint
/polygon_from_boundingbox

### Parameters
#### Request Body
- **bounding_box** (list[str]) - Required - A list of four strings representing the bounding box coordinates: [min_lat, max_lat, min_lon, max_lon].

### Request Example
```json
{
  "bounding_box": ["40.9", "41.5", "-8.8", "-8.4"]
}
```

### Response
#### Success Response (200)
- **polygon** (shapely.geometry.Polygon) - The generated Shapely Polygon object.

#### Response Example
```json
{
  "polygon": "<Shapely Polygon object>"
}
```
```

--------------------------------

### Randomize geographic coordinates using Python

Source: https://github.com/hugodscarvalho/rancoord/blob/main/README.md

Generates random coordinates within a defined polygon, with options to save the output as a JSON file and a map as an HTML file.

```python
lat, lon = coordinates_randomizer(polygon = poly, num_locations = 50, plot = True, save = True)
```

--------------------------------

### plot_coordinates(lat, lon, zoom, save)

Source: https://github.com/hugodscarvalho/rancoord/blob/main/README.md

Generates a Folium map visualization for a set of coordinates.

```APIDOC
## plot_coordinates(lat, lon, zoom, save)

### Description
Function to calculate the average of a list of numbers in order to center geographical map.

### Parameters
- **lat** (List) - Required - List of numbers.
- **lon** (List) - Required - List of numbers.
- **zoom** (Integer) - Optional - Zoom level of the map. Defaults to 11.
- **save** (Boolean) - Optional - If True, the map will be saved. Defaults to True.

### Response
- **Returns** (Folium Map) - Folium map with the coordinates.

### Request Example
```python
map = plot_coordinates(lat = lat, lon = lon, zoom = 11, save = True)
```
```

--------------------------------

### Calculate Driving Distance with OSRM

Source: https://context7.com/hugodscarvalho/rancoord/llms.txt

Compute actual road distance using the OSRM API. Requires an active internet connection.

```python
import rancoord as rc

# Calculate driving distance using OSRM API
# Requires internet connection
driving_distance = rc.osrm_distance(
    pickup_lat=41.4781,
    pickup_long=-8.1992,
    dropoff_lat=40.8761,
    dropoff_long=-9.1222,
    miles=False
)

print(f"Driving distance: {driving_distance} km")
# Returns actual road distance, which is longer than straight-line distance

# Compare with straight-line distance
straight_line = rc.vincenty_distance(
    pickup_lat=41.4781,
    pickup_long=-8.1992,
    dropoff_lat=40.8761,
    dropoff_long=-9.1222
)
print(f"Straight-line distance: {straight_line} km")
```

--------------------------------

### Geocode an address using nominatim_geocoder

Source: https://github.com/hugodscarvalho/rancoord/blob/main/README.md

Retrieves the bounding box coordinates for a specified address string.

```python

bounding_box = nominatim_geocoder(address = 'Barcelona, Spain')

```

--------------------------------

### nominatim_geocoder(address)

Source: https://github.com/hugodscarvalho/rancoord/blob/main/README.md

Geocodes an address using the Nominatim service to retrieve its bounding box.

```APIDOC
## nominatim_geocoder(address)

### Description
Function to geocode an address using the Nominatim geocoder and return the bounding box of the address.

### Parameters
- **address** (String) - Required - Address to geocode.

### Response
- **Returns** (List) - List of coordinates of the bounding box of the address.

### Request Example
```python
bounding_box = nominatim_geocoder(address = 'Barcelona, Spain')
```
```

--------------------------------

### Geocode addresses with nominatim_geocoder

Source: https://context7.com/hugodscarvalho/rancoord/llms.txt

Retrieve bounding box coordinates for a location string to define geographic regions.

```python
import rancoord as rc

# Get bounding box for a city or region
bounding_box = rc.nominatim_geocoder('Barcelona, Spain')

# Returns: ['41.2975', '41.4682', '2.0526', '2.2262']
# Format: [min_lat, max_lat, min_lon, max_lon]
print(f"Bounding box: {bounding_box}")

# Use with polygon_from_boundingbox to create a polygon
polygon = rc.polygon_from_boundingbox(bounding_box)

# Generate coordinates within Barcelona
lat, lon, _ = rc.coordinates_randomizer(polygon=polygon, num_locations=20)
```

--------------------------------

### Plot coordinates using plot_coordinates

Source: https://github.com/hugodscarvalho/rancoord/blob/main/README.md

Generates a Folium map object from latitude and longitude lists.

```python

map = plot_coordinates(lat = lat, lon = lon, zoom = 11, save = True)

```

--------------------------------

### multiple_formats_saver

Source: https://github.com/hugodscarvalho/rancoord/blob/main/README.md

Saves latitude and longitude coordinates in specified formats (CSV, JSON, TXT, XLSX).

```APIDOC
## multiple_formats_saver

### Description
Saves the coordinates lat and lon with specified column names. The coordinates are saved in a user-defined format (csv, json, txt, xlsx) and file name, within a user-specified directory.

### Method
N/A (This is a function call, not an HTTP endpoint)

### Endpoint
N/A

### Parameters
#### Arguments
- **lat** (List) - Required - List of latitude values.
- **lon** (List) - Required - List of longitude values.
- **columns** (List) - Optional - Column names. Defaults to ['Latitude', 'Longitude'].
- **file_format** (String) - Optional - File format. Defaults to 'json'. Possible values: csv, json, txt, xlsx.
- **file_name** (String) - Optional - File name. Defaults to 'coordinates'.
- **dir_name** (String) - Optional - Directory name. Defaults to 'coordinates'.

### Request Example
```python
multiple_formats_saver(lat = lat, lon = lon, columns = ['Latitude', 'Longitude'], file_format = 'json', file_name = 'coordinates', dir_name = 'coordinates')
```

### Response
#### Success Response (200)
- None: The function does not return any value.

#### Response Example
None
```

--------------------------------

### Calculate distance with vincenty_distance

Source: https://github.com/hugodscarvalho/rancoord/blob/main/README.md

Calculates the distance between two points on the Earth's surface using Vincenty's formula. Returns distance in kilometers by default.

```python
vincenty = vincenty_distance(pickup_lat = 41.4781, pickup_long = -8.1992 , dropoff_lat = 40.8761 , dropoff_long = -9.1222, miles = False)
```

--------------------------------

### Calculate distance with vincenty_distance

Source: https://context7.com/hugodscarvalho/rancoord/llms.txt

Compute geodesic distance using Vincenty's formula for higher accuracy on the Earth's ellipsoid.

```python
import rancoord as rc

# Calculate distance between two points in Portugal
```

--------------------------------

### Calculate distance matrix with haversine_distance

Source: https://github.com/hugodscarvalho/rancoord/blob/main/README.md

Computes a distance matrix for given latitude and longitude lists using a specified method.

```python
haversine = haversine_distance(lat = lat, lon = lon, method = 'osrm')
```

--------------------------------

### nominatim_geocoder

Source: https://context7.com/hugodscarvalho/rancoord/llms.txt

Geocodes an address string using the Nominatim service to retrieve bounding box coordinates. This is useful for defining geographic regions programmatically.

```APIDOC
## GET /nominatim_geocoder

### Description
Geocodes an address string using the Nominatim service and returns its bounding box coordinates.

### Method
GET

### Endpoint
/nominatim_geocoder

### Parameters
#### Query Parameters
- **address** (str) - Required - The address string to geocode.

### Response
#### Success Response (200)
- **bounding_box** (list[str]) - A list containing the bounding box coordinates in the format [min_lat, max_lat, min_lon, max_lon].

#### Response Example
```json
{
  "bounding_box": ["41.2975", "41.4682", "2.0526", "2.2262"]
}
```
```

--------------------------------

### Generate Random Coordinates and Distance Matrix

Source: https://context7.com/hugodscarvalho/rancoord/llms.txt

Generates a specified number of random coordinates within a given polygon. Optionally saves an interactive map and the coordinates to a file, and computes the distance matrix between all generated points.

```python
lat, lon, dist_matrix = rc.coordinates_randomizer(
    polygon=polygon,
    num_locations=25,
    plot=True,      # Save interactive map
    save=True,      # Save coordinates to file
    matrix=True     # Compute distance matrix
)
```

--------------------------------

### Calculate distance with osrm_distance

Source: https://github.com/hugodscarvalho/rancoord/blob/main/README.md

Retrieves the distance between coordinates using the OSRM API. Requires network access to the OSRM service.

```python
osrm = osrm_distance(pickup_lat = 41.4781, pickup_long = -8.1992 , dropoff_lat = 40.8761 , dropoff_long = -9.1222, miles = False)
```

--------------------------------

### coordinates_randomizer

Source: https://context7.com/hugodscarvalho/rancoord/llms.txt

Generates random geographic coordinates within a specified polygon. It can optionally plot the coordinates on a map, save them to files, and compute a distance matrix between all generated points.

```APIDOC
## POST /coordinates_randomizer

### Description
Generates random geographic coordinates within a polygon. Optionally plots them on a map, saves them to files, and computes a distance matrix.

### Method
POST

### Endpoint
/coordinates_randomizer

### Parameters
#### Request Body
- **polygon** (shapely.geometry.Polygon) - Required - The polygon within which to generate coordinates.
- **num_locations** (int) - Required - The number of random locations to generate.
- **plot** (bool) - Optional - If True, saves an interactive HTML map to the /maps folder.
- **save** (bool) - Optional - If True, exports coordinates to the /coordinates folder.
- **matrix** (bool) - Optional - If True, computes the distance matrix between all points.

### Request Example
```json
{
  "polygon": "<Shapely Polygon object>",
  "num_locations": 50,
  "plot": true,
  "save": true,
  "matrix": true
}
```

### Response
#### Success Response (200)
- **lat** (list[float]) - A list of generated latitudes.
- **lon** (list[float]) - A list of generated longitudes.
- **distance_matrix** (numpy.ndarray) - A matrix of distances between all generated points (only if matrix=True).

#### Response Example
```json
{
  "lat": [41.15, 41.16, ...],
  "lon": [-8.63, -8.62, ...],
  "distance_matrix": [[0.0, 1.2, ...], [1.2, 0.0, ...], ...]
}
```
```

--------------------------------

### vincenty_distance

Source: https://github.com/hugodscarvalho/rancoord/blob/main/README.md

Calculates the distance between two points on the Earth's surface using Vincenty's formula.

```APIDOC
## vincenty_distance

### Description
Calculates the distance between two points on the Earth's surface using Vincenty's formula. The output is in kilometers by default.

### Method
N/A (This is a function call, not an HTTP endpoint)

### Endpoint
N/A

### Parameters
#### Arguments
- **pickup_lat** (float) - Required - The latitude of the pickup location.
- **pickup_long** (float) - Required - The longitude of the pickup location.
- **dropoff_lat** (float) - Required - The latitude of the dropoff location.
- **dropoff_long** (float) - Required - The longitude of the dropoff location.
- **miles** (Boolean) - Optional - If True, the output will be in miles. If False, the output will be in kilometers. Defaults to False.

### Request Example
```python
vincenty = vincenty_distance(pickup_lat = 41.4781, pickup_long = -8.1992 , dropoff_lat = 40.8761 , dropoff_long = -9.1222, miles = False)
```

### Response
#### Success Response (200)
- **float**: The distance between two points on the earth using the vincenty's formula.
```

--------------------------------

### osrm_distance

Source: https://github.com/hugodscarvalho/rancoord/blob/main/README.md

Calculates the distance between two coordinates using the OSRM API.

```APIDOC
## osrm_distance

### Description
Calculates the distance between pickup and dropoff coordinates using the OSRM API. The distance is returned in kilometers by default.

### Method
N/A (This is a function call, not an HTTP endpoint)

### Endpoint
N/A

### Parameters
#### Arguments
- **pickup_lat** (float) - Required - The latitude of the pickup location.
- **pickup_long** (float) - Required - The longitude of the pickup location.
- **dropoff_lat** (float) - Required - The latitude of the dropoff location.
- **dropoff_long** (float) - Required - The longitude of the dropoff location.
- **miles** (Boolean) - Optional - If True, the output will be in miles. If False, the output will be in kilometers. Defaults to False.

### Request Example
```python
osrm = osrm_distance(pickup_lat = 41.4781, pickup_long = -8.1992 , dropoff_lat = 40.8761 , dropoff_long = -9.1222, miles = False)
```

### Response
#### Success Response (200)
- **float**: The distance between two coordinates.
```

--------------------------------

### distance_matrix

Source: https://github.com/hugodscarvalho/rancoord/blob/main/README.md

Calculates a matrix of distances between pairs of geographic coordinates using specified methods.

```APIDOC
## distance_matrix(lat, lon, method)

### Description
For each pair of geographic coordinates, calculate the distance between them using the specified method and return a matrix of distances.

### Parameters
#### Arguments
- **lat** (List) - Required - List of latitudes.
- **lon** (List) - Required - List of longitudes.
- **method** (String) - Required - The method to use to calculate the distances. 'haversine', 'vincenty' or 'osrm'. Vincenty's distance by default.

### Response
- **numpy.ndarray** - A matrix of distances between each pair of coordinates.

### Request Example
```python
haversine = haversine_distance(lat = lat, lon = lon, method = 'osrm')
```
```

--------------------------------

### Calculate list average using list_average

Source: https://github.com/hugodscarvalho/rancoord/blob/main/README.md

Computes the average of a list of numbers, typically used for centering maps.

```python

avg = list_average(list_of_numbers = [1, 2, 2, 3, 6, 7])

```

--------------------------------

### Calculate distance with haversine_distance

Source: https://context7.com/hugodscarvalho/rancoord/llms.txt

Compute the great-circle distance between two points in kilometers or miles.

```python
import rancoord as rc

# Calculate distance between Porto and Lisbon
pickup_lat, pickup_long = 41.1579, -8.6291   # Porto
dropoff_lat, dropoff_long = 38.7223, -9.1393  # Lisbon

# Distance in kilometers (default)
distance_km = rc.haversine_distance(
    pickup_lat=pickup_lat,
    pickup_long=pickup_long,
    dropoff_lat=dropoff_lat,
    dropoff_long=dropoff_long,
    miles=False
)
print(f"Distance (km): {distance_km}")  # Output: ~274.5 km

# Distance in miles
distance_miles = rc.haversine_distance(
    pickup_lat=pickup_lat,
    pickup_long=pickup_long,
    dropoff_lat=dropoff_lat,
    dropoff_long=dropoff_long,
    miles=True
)
print(f"Distance (miles): {distance_miles}")  # Output: ~170.5 miles
```

--------------------------------

### Calculate distance with haversine_distance

Source: https://github.com/hugodscarvalho/rancoord/blob/main/README.md

Computes the great-circle distance between two points on a sphere. Set miles to True for imperial units or False for metric.

```python
haversine = haversine_distance(pickup_lat = 41.4781, pickup_long = -8.1992 , dropoff_lat = 40.8761 , dropoff_long = -9.1222, miles = False)
```

--------------------------------

### vincenty_distance

Source: https://context7.com/hugodscarvalho/rancoord/llms.txt

Calculates the geodesic distance between two points using Vincenty's formula, offering higher accuracy for the Earth's ellipsoidal shape compared to the Haversine formula. The distance is returned in kilometers.

```APIDOC
## POST /vincenty_distance

### Description
Calculates the geodesic distance between two points using Vincenty's formula.

### Method
POST

### Endpoint
/vincenty_distance

### Parameters
#### Request Body
- **pickup_lat** (float) - Required - Latitude of the first point.
- **pickup_long** (float) - Required - Longitude of the first point.
- **dropoff_lat** (float) - Required - Latitude of the second point.
- **dropoff_long** (float) - Required - Longitude of the second point.

### Request Example
```json
{
  "pickup_lat": 41.1579,
  "pickup_long": -8.6291,
  "dropoff_lat": 38.7223,
  "dropoff_long": -9.1393
}
```

### Response
#### Success Response (200)
- **distance** (float) - The calculated geodesic distance in kilometers.

#### Response Example
```json
{
  "distance": 274.1
}
```
```

--------------------------------

### Define Geographical Polygon

Source: https://github.com/hugodscarvalho/rancoord/blob/main/README.md

Define a geographical polygon using a list of coordinate tuples. This polygon will be used to generate random coordinates within its boundaries. Ensure the coordinates form a closed loop.

```python
poly = Polygon(
    [
        (38.78562804689748, -9.47276949903965),
        (38.713870245772654, -9.139059782242775),
        (38.89740476139506, -9.055975675797463),
        (38.96871087768789, -8.969115019059181),
        (39.05061092686942, -8.92894625685215),
        (39.08579612091302, -9.407538175797463),
        (38.984457987516386, -9.397238493180275),
    ]
)
```

--------------------------------

### haversine_distance

Source: https://github.com/hugodscarvalho/rancoord/blob/main/README.md

Calculates the great-circle distance between two points on a sphere using the Haversine formula.

```APIDOC
## haversine_distance

### Description
Calculates the great-circle distance between two points on a sphere given their longitudes and latitudes using the Haversine formula.

### Method
N/A (This is a function call, not an HTTP endpoint)

### Endpoint
N/A

### Parameters
#### Arguments
- **pickup_lat** (float) - Required - The latitude of the pickup location.
- **pickup_long** (float) - Required - The longitude of the pickup location.
- **dropoff_lat** (float) - Required - The latitude of the dropoff location.
- **dropoff_long** (float) - Required - The longitude of the dropoff location.
- **miles** (Boolean) - Optional - If True, the output will be in miles. If False, the output will be in kilometers. Defaults to False.

### Request Example
```python
haversine = haversine_distance(pickup_lat = 41.4781, pickup_long = -8.1992 , dropoff_lat = 40.8761 , dropoff_long = -9.1222, miles = False)
```

### Response
#### Success Response (200)
- **float**: The distance between two points on a sphere.
```

--------------------------------

### haversine_distance

Source: https://context7.com/hugodscarvalho/rancoord/llms.txt

Calculates the great-circle distance between two geographic points using the Haversine formula. The distance can be returned in kilometers or miles.

```APIDOC
## POST /haversine_distance

### Description
Calculates the great-circle distance between two geographic points using the Haversine formula.

### Method
POST

### Endpoint
/haversine_distance

### Parameters
#### Request Body
- **pickup_lat** (float) - Required - Latitude of the first point.
- **pickup_long** (float) - Required - Longitude of the first point.
- **dropoff_lat** (float) - Required - Latitude of the second point.
- **dropoff_long** (float) - Required - Longitude of the second point.
- **miles** (bool) - Optional - If True, returns the distance in miles; otherwise, returns in kilometers (default).

### Request Example
```json
{
  "pickup_lat": 41.1579,
  "pickup_long": -8.6291,
  "dropoff_lat": 38.7223,
  "dropoff_long": -9.1393,
  "miles": false
}
```

### Response
#### Success Response (200)
- **distance** (float) - The calculated distance between the two points in kilometers or miles.

#### Response Example
```json
{
  "distance": 274.5
}
```
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.