### Map Matching API Request Example

Source: https://docs.gebeta.app/docs/map-matching

Example of a GET request with specific coordinate data and parameters.

```bash
curl --location -g --request GET 'https://mapapi.gebeta.app/api/route/matching/?path=[{9.019797,38.743688},{9.020316,38.74401},{9.020571,38.743619},{9.020883,38.743538},{9.020799,38.743876},{9.020952,38.744177}]&apiKey={your-api-key}&radius=1'
```

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

### Install Gebeta GL Plugin

Source: https://docs.gebeta.app/docs/tiles/flutter

Run this command in your terminal to add the dependency to your Flutter project.

```bash
flutter pub add gebeta_gl
```

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

### Success Response Example for Places Query

Source: https://docs.gebeta.app/gebeta-api.openapi.json

Example JSON response structure for a successful request to retrieve places.

```json
{
  "msg": "ok",
  "data": [
    {
      "id": 103566,
      "name": "Welkite",
      "latitude": 8.992,
      "longitude": 38.774,
      "Country": "ethiopia",
      "City": "addis ababa",
      "type": "city",
      "details": "{}"
    }
  ]
}
```

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

### Fetch Directions with JavaScript

Source: https://docs.gebeta.app/docs/direction

Example of using the fetch API to retrieve route data from the Directions endpoint.

```javascript
fetch('https://mapapi.gebeta.app/api/route/direction/?origin={8.989022,38.79036}&destination={9.03045,38.76530}&apiKey=your-api-key')
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));
```

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

### TSS Endpoint API Key Example

Source: https://docs.gebeta.app/gebeta-api.openapi.json

Placeholder value for the required API key parameter.

```text
your_api_key_here
```

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

### TSS Endpoint Successful Response Example

Source: https://docs.gebeta.app/gebeta-api.openapi.json

Example of a successful JSON response from the TSS optimization endpoint.

```json
{
  "msg": "Optimization completed successfully",
  "bestorder": [0, 2, 1, 0],
  "timetaken": 10840.284,
  "totalDistance": 32520.854,
  "originalorder": [0, 1, 2],
  "direction": [
    [8.98755168914795, 38.764892578125],
    [8.987594604492188, 38.76495361328125],
    [8.987668991088867, 38.76502990722656]
  ]
}
```

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

### Initialize GebetaMap Widget

Source: https://docs.gebeta.app/docs/tiles/flutter

A full implementation example showing how to load a map style from assets and display the GebetaMap widget within a FutureBuilder.

```dart
import 'package:flutter/material.dart';
import 'package:gebeta_gl/gebeta_gl.dart';
 
 
class MyHomePage extends StatefulWidget {
  const MyHomePage({super.key, required this.title});
 
  final String title;
 
  @override
  State<MyHomePage> createState() => _MyHomePageState();
}
 
class _MyHomePageState extends State<MyHomePage> {
  // Your API key
  final String apiKey = 'your api key';
 
  @override
  void initState() {
    super.initState();
  }
  
  @override
  void dispose() {
    super.dispose();
  }
  
  // Function to load the map style
  Future<String> loadMapStyle() async {
    return await rootBundle.loadString('assets/styles/basic.json');
  }
 
  Future<Uint8List> loadMarkerImage() async {
    var byteData = await rootBundle.load("assets/marker-black.png");
    return byteData.buffer.asUint8List();
  }
 
    @override
    Widget build(BuildContext context) {
        return Scaffold(
        body: FutureBuilder<String>(
            future: loadMapStyle(), // Load the JSON style file
            builder: (BuildContext context, AsyncSnapshot<String> snapshot) {
            if (snapshot.connectionState == ConnectionState.waiting) {
                // While the future is loading, show a loading spinner
                return Center(child: CircularProgressIndicator());
            } else if (snapshot.hasError) {
                // If the future completed with an error, show an error message
                print(snapshot.error);
                return Center(child: Text('Error loading map style'));
            } else if (snapshot.hasData) {
                // If the future completed successfully, show the map
                String styleString = snapshot.data!;
                return GebetaMap(
                compassViewPosition: CompassViewPosition.topRight,
                styleString: styleString,
                initialCameraPosition: CameraPosition(
                    target: LatLng(9.0192, 38.7525), // Addis Ababa
                    zoom: 10.0,
                ),
                apiKey: apiKey,
                );
            } else {
                // Handle any other unexpected states
                return Center(child: Text('No map style found'));
            }
            },
        ),
        );
    }
}
```

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

### Send a GET request to the VRP API

Source: https://docs.gebeta.app/docs/vrp

Use this command to initiate a basic request to the VRP API endpoint.

```bash
curl https://docs.gebeta.app/api/optimized-trip?apiKey={your-api-key}
```

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

### Forward Geocoding cURL Examples

Source: https://docs.gebeta.app/docs/geocoding/geocoding-forward

Various cURL commands demonstrating basic searches, proximity biasing, country filtering, and result limiting.

```bash
# A basic forward geocoding request
curl "https://mapapi.gebeta.app/v2/search/geocode?query=Bole+Road&apiKey=YOUR_API_KEY"
 
# Find 'Chester' with a proximity bias coordinate
curl "https://mapapi.gebeta.app/v2/search/geocode?query=chester&proximity=-74.70850,40.78375&apiKey=YOUR_API_KEY"
 
# Filter forward search results to only return matches within Ethiopia (ET)
curl "https://mapapi.gebeta.app/v2/search/geocode?query=Bole&country=et&apiKey=YOUR_API_KEY"
 
# Limit the results to 2 results using the limit option
curl "https://mapapi.gebeta.app/v2/search/geocode?query=Washington&limit=2&apiKey=YOUR_API_KEY"
```

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

### JavaScript Route Optimization Fetch

Source: https://docs.gebeta.app/docs/route-optimization

Example of using the fetch API in JavaScript to retrieve route data.

```javascript
fetch('https://mapapi.gebeta.app/api/route/tss/?json=[{8.989022,38.79036},{9.03045,38.76530}]&apiKey={your-api-key}')
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));
```

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

### Matrix API Request via JavaScript

Source: https://docs.gebeta.app/docs/matrix

Example of fetching matrix data using the JavaScript fetch API.

```javascript
fetch('https://mapapi.gebeta.app/api/route/matrix/?json=[{8.989022,38.79036},{9.03045,38.76530}]&apiKey={your-api-key}')
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));
```

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

### TSS Endpoint Coordinate Input Example

Source: https://docs.gebeta.app/gebeta-api.openapi.json

Example of the JSON-formatted string representing geographic coordinates for the TSS endpoint.

```json
[[8.987685259188599, 38.764792722654455], [8.9879443, 38.7651287], [9.087685259188599, 38.764792722654455]]
```

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

### Execute Route Calculation with cURL

Source: https://docs.gebeta.app/api-playground

Example request to the /api/route/onm/ endpoint using cURL. Requires valid origin, destination JSON array, and an API key.

```shell
curl 'https://docs.gebeta.app/api/route/onm/?origin=%7B8.457685259188599%2C38.764792722654455%7D&json=%5B%7B8.987685259188599%2C38.764792722654455%7D%2C%7B9.087685259188599%2C38.764792722654455%7D%5D&apiKey=your-api-key-here'
```

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

### GET /api/route/matrix/

Source: https://docs.gebeta.app/docs/matrix

Calculates travel times and distances between multiple specified locations.

```APIDOC
## GET /api/route/matrix/

### Description
Calculates travel times and distances between multiple origins and destinations provided as latitude and longitude pairs.

### Method
GET

### Endpoint
https://mapapi.gebeta.app/api/route/matrix/

### Parameters
#### Query Parameters
- **json** (string) - Required - An array of semicolon-separated latitude and longitude pairs to specify which places to visit along the way.
- **apiKey** (string) - Required - Your API key for accessing Gebeta Maps.

### Request Example
curl "https://mapapi.gebeta.app/api/route/matrix/?json=[{8.989022,38.79036},{9.03045,38.76530}]&apiKey={your-api-key}"

### Response
#### Success Response (200)
- **OK** - The request was successful. The system found a valid route and returned the requested data.

#### Error Responses
- **404 (NoRoute)** - No route exists between the specified locations.
- **401 (Not Authorized)** - Authentication failed due to missing or invalid token.
- **422 (InvalidInput)** - The request parameters are incorrect.
```

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

### GET /nearby

Source: https://docs.gebeta.app/gebeta-api.openapi.json

Retrieves a list of nearby locations based on specified parameters.

```APIDOC
## GET /nearby

### Description
Retrieves a list of nearby locations based on geographic coordinates and specified filters.

### Method
GET

### Endpoint
/nearby

### Parameters
#### Query Parameters
- **lat** (string) - Required - Latitude coordinate.
- **lng** (string) - Required - Longitude coordinate.
- **apiKey** (string) - Required - API key used for authenticating requests.
- **type** (string) - Required - The type of place to retrieve (e.g., 'terminal', 'warehouse', 'office').
- **detailLevel** (string) - Required - Level of detail for the response.
- **limit** (string) - Required - Maximum number of nearby locations to return.

### Response
#### Success Response (200)
- **data** (object) - Returns a JSON object containing the requested location details.
```

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

### Forward Geocoding JSON Response

Source: https://docs.gebeta.app/docs/geocoding/geocoding-forward

Example of the JSON structure returned by the forward geocoding endpoint.

```json
{
  "data": {
    "query": "Bole Road",
    "results": [
      {
        "id": "way:123456",
        "name": "Bole Road",
        "display_name": "Bole Road, Addis Ababa, Ethiopia",
        "category": "highway",
        "location": {
          "lat": 9.019185,
          "lng": 38.757812
        },
        "address": {
          "city": "Addis Ababa",
          "country": "Ethiopia",
          "country_code": "ETH"
        }
      }
    ]
  }
}
```

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

### Embed Map in HTML Page

Source: https://docs.gebeta.app/docs/embed-your-map

Example of integrating the Gebeta map iframe into a standard HTML document structure.

```html
<!-- Example: adding the embed to a plain HTML page -->
<!DOCTYPE html>
<html>
  <body>
    <h1>Find Us</h1>
    <iframe
      src="https://maps.gebeta.app/embed/map?t=eyJ..."
      width="100%"
      height="450"
      style="border:0;border-radius:8px"
      allowfullscreen
      loading="lazy"
    ></iframe>
  </body>
</html>
```

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

### GET /api/route/onm/

Source: https://docs.gebeta.app/docs/onm

Calculates travel times and distances between an origin and a set of waypoints.

```APIDOC
## GET /api/route/onm/

### Description
Calculates the best routes between a specified origin and multiple destinations provided as waypoints.

### Method
GET

### Endpoint
https://mapapi.gebeta.app/api/route/onm/

### Parameters
#### Query Parameters
- **origin** (string) - Required - The origin in latitude and longitude format, e.g., {longitude, latitude}.
- **json** (string[]) - Required - An array of semicolon-separated latitude and longitude pairs to specify which places to visit along the way.
- **apiKey** (string) - Required - Your API key for accessing Gebeta Maps.

### Response
#### Success Response (200)
- **OK** - The request was successful. The system found a valid route and returned the requested data.

#### Error Responses
- **404 (NoRoute)** - No route exists between the specified locations.
- **401 (Not Authorized)** - Authentication failed due to missing or invalid token.
- **422 (InvalidInput)** - The request parameters are incorrect.
```

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

### GET /api/route/matching/

Source: https://docs.gebeta.app/docs/map-matching

Matches a series of GPS coordinates to the most likely path on the road network.

```APIDOC
## GET /api/route/matching/

### Description
Matches a series of GPS coordinates to the most likely path on the road network, correcting for GPS drift and inaccuracies.

### Method
GET

### Endpoint
https://mapapi.gebeta.app/api/route/matching/

### Parameters
#### Query Parameters
- **path** (array) - Required - Array of coordinate objects in format [{lat,lng},{lat,lng}]
- **apiKey** (string) - Required - Your API key for accessing Gebeta Maps
- **radius** (number) - Required - Search radius in meters for matching coordinates to roads (default: 1)

### Request Example
curl --location -g --request GET 'https://mapapi.gebeta.app/api/route/matching/?path=[{9.019797,38.743688},{9.020316,38.74401},{9.020571,38.743619},{9.020883,38.743538},{9.020799,38.743876},{9.020952,38.744177}]&apiKey={your-api-key}&radius=1'

### Response
#### Success Response (200)
- **OK** - The request was successful. The system matched the path and returned the corrected route.

#### Error Responses
- **404** - NoRoute: No matching route found for the provided coordinates.
- **401** - Not Authorized: Authentication failed due to missing or invalid token.
- **422** - InvalidInput: The request parameters are incorrect.
```

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

### GET /api/route/direction/

Source: https://docs.gebeta.app/docs/direction

Retrieves the optimal route between two locations, including travel time, distance, and turn-by-turn instructions.

```APIDOC
## GET /api/route/direction/

### Description
Retrieves the optimal route between an origin and a destination. Supports optional intermediate waypoints.

### Method
GET

### Endpoint
https://mapapi.gebeta.app/api/route/direction/

### Parameters
#### Query Parameters
- **origin** (string) - Required - Specifies the latitude and longitude of the origin location in the format lat,lon.
- **destination** (string) - Required - Specifies the latitude and longitude of the destination location in the format lat,lon.
- **apiKey** (string) - Required - Your API key for accessing Gebeta Maps.
- **waypoints** (string[]) - Optional - An array of latitude and longitude pairs (formatted as "lat,lon") separated by semicolons, indicating intermediate locations.

### Response
#### Success Response (200)
- **OK** - The request was successful. The system found a valid route and returned the requested data.

#### Error Responses
- **401** - Not Authorized (No Token or Invalid Token)
- **404** - NoRoute (No route exists between the specified locations)
- **422** - InvalidInput (Request parameters are incorrect)
```

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

### GET /api/v1/route/findowned

Source: https://docs.gebeta.app/gebeta-api.openapi.json

Retrieve stored addresses from the Gebeta database that match a specific name and type.

```APIDOC
## GET /api/v1/route/findowned

### Description
Retrieve stored addresses from the Gebeta database that match a specific name and type. This endpoint allows users to query places they own or have registered.

### Method
GET

### Endpoint
/api/v1/route/findowned

### Parameters
#### Query Parameters
- **name** (string) - Required - The name of the stored place you are searching for.
- **type** (string) - Required - The type of place you are looking for (e.g., 'city', 'neighborhood', 'landmark').
```

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

### GET /api/route/tss/

Source: https://docs.gebeta.app/docs/route-optimization

Retrieves the optimized route for a sequence of locations provided as latitude and longitude pairs.

```APIDOC
## GET /api/route/tss/

### Description
Calculates the most efficient route between multiple specified locations.

### Method
GET

### Endpoint
https://mapapi.gebeta.app/api/route/tss/

### Parameters
#### Query Parameters
- **json** (string[]) - Required - An array of semicolon-separated latitude and longitude pairs to specify which places to visit along the way.
- **apiKey** (string) - Required - Your API key for accessing Gebeta Maps.

### Request Example
curl "https://mapapi.gebeta.app/api/route/tss/?json=[{8.989022,38.79036},{9.03045,38.76530}]&apiKey={your-api-key}"

### Response
#### Success Response (200)
- **OK** - The request was successful. The system found a valid route and returned the requested data.

#### Error Responses
- **404 (NoRoute)** - No route exists between the specified locations.
- **401 (Not Authorized)** - Authentication failed due to missing or invalid token.
- **422 (InvalidInput)** - The request parameters are incorrect.
```

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

### Successful Route Response Example

Source: https://docs.gebeta.app/gebeta-api.openapi.json

A JSON object representing a successful response from the direction endpoint, containing travel time, distance, and route coordinates.

```json
{
  "msg": "Ok",
  "timetaken": 5102.905,
  "totalDistance": 15308.715,
  "direction": [
    [9.18759536743164, 38.763946533203125],
    [9.187566757202148, 38.763954162597656],
    [9.1875581741333, 38.763362884521484],
    [9.1875581741333, 38.763362884521484],
    [9.1875581741333, 38.763362884521484],
    [9.187539100646973, 38.76198959350586],
    [9.187505722045898, 38.76165771484375]
  ]
}
```

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

### Reverse Geocoding Response Format

Source: https://docs.gebeta.app/docs/geocoding/geocoding-reverse

Example JSON response structure returned by the reverse geocoding endpoint.

```json
{
  "data": {
    "query": "9.019200,38.757800",
    "results": [
      {
        "id": "way:123456",
        "name": "Bole Road",
        "display_name": "Bole Road, Addis Ababa, Ethiopia",
        "category": "highway",
        "location": {
          "lat": 9.019185,
          "lng": 38.757812
        },
        "address": {
          "city": "Addis Ababa",
          "country": "Ethiopia",
          "country_code": "ETH"
        }
      }
    ]
  }
}
```

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

### GET /api/v1/route/geocoding

Source: https://docs.gebeta.app/gebeta-api.openapi.json

Search for a place by name. The endpoint returns a list of matching places with details such as location (latitude and longitude), city, country, and type.

```APIDOC
## GET /api/v1/route/geocoding

### Description
Search for a place by name. The endpoint returns a list of matching places with details such as location (latitude and longitude), city, country, and type (e.g., neighborhood, landmark).

### Method
GET

### Endpoint
/api/v1/route/geocoding

### Parameters
#### Query Parameters
- **name** (string) - Required - The name of the place to search for. Can be a full or partial name (e.g., 'meskel').
- **apiKey** (string) - Required - API key used for authenticating the request.

### Response
#### Success Response (200)
- **data** (array) - List of matching places.
- **msg** (string) - Status message describing the result (e.g., 'ok').

#### Response Example
{
  "data": [
    {
      "city": "Addis Ababa",
      "country": "Ethiopia",
      "lat": 8.978027,
      "lng": 38.884797,
      "name": "bole arabsa",
      "type": "neighborhood"
    }
  ],
  "msg": "ok"
}
```

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

### GET /api/v1/route/geocoding

Source: https://docs.gebeta.app/gebeta-api.openapi.json

Retrieves a list of places that match a specified name and are located within a defined geographic bounding box.

```APIDOC
## GET /api/v1/route/geocoding{?bound}

### Description
Retrieves a list of places that match a specified name and are located within a defined geographic bounding box. Useful for limiting results to a specific area on a map.

### Method
GET

### Endpoint
/api/v1/route/geocoding

### Parameters
#### Query Parameters
- **name** (string) - Required - The name of the place to search for. Can be a full or partial name (e.g., 'edna mall').
- **bound** (string) - Required - A comma-separated string defining the bounding box coordinates in the format `minLng,minLat,maxLng,maxLat`.
- **apiKey** (string) - Required - API key required for authenticating the request.
```

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

### GET /api/v1/route/geocoding (Filter)

Source: https://docs.gebeta.app/gebeta-api.openapi.json

Retrieves a list of places that match a specified name and are located within a specified country and city.

```APIDOC
## GET /api/v1/route/geocoding{?filter}

### Description
Retrieves a list of places that match a specified name and are located within a specified country and city. This endpoint allows clients to filter places using location-based attributes.

### Method
GET

### Endpoint
/api/v1/route/geocoding

### Parameters
#### Query Parameters
- **name** (string) - Required - The name of the place to search for.
- **filter** (string) - Required - A filter string used to narrow down search results based on location. The format must be `country:<countryName>|city:<cityName>`.
- **apiKey** (string) - Required - API key for authenticating the request.
```

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

### GET /api/route/onm/

Source: https://docs.gebeta.app/api-playground

Calculates routes from a single origin to multiple destinations, returning travel times, distances, and paths. This helps determine which destination is nearest in terms of actual travel cost.

```APIDOC
## GET /api/route/onm/

### Description
Calculates routes from a single origin to multiple destinations, returning travel times, distances, and paths. Helps determine which destination is nearest in terms of actual travel cost.

### Method
GET

### Endpoint
/api/route/onm/

### Parameters
#### Query Parameters
- **origin** (string) - Required - A single origin coordinate pair in the format {lat,lon}. Example: {8.457685259188599,38.764792722654455}
- **json** (string) - Required - An array of destination coordinate pairs in the format [{lat1,lon1},{lat2,lon2},...].
- **apiKey** (string) - Required - API key used for authentication and usage control.

### Response
#### Success Response (200)
- **msg** (string) - Status message
- **directions** (array) - List of computed routes

#### Response Example
{
  "msg": "Ok",
  "directions": [
    {
      "msg": "Ok",
      "timetaken": 27145.13,
      "totalDistance": 81435.39,
      "direction": [
        [9.067654609680176, 38.75811004638672],
        [9.067713737487793, 38.75811767578125]
      ]
    }
  ]
}
```

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

### GET /api/v1/route/revgeocoding

Source: https://docs.gebeta.app/gebeta-api.openapi.json

Retrieve place information based on latitude and longitude coordinates. This endpoint returns details such as place name, location, country, city, and type.

```APIDOC
## GET /api/v1/route/revgeocoding

### Description
Retrieve place information based on latitude and longitude coordinates. This endpoint returns details such as place name, location, country, city, and type.

### Method
GET

### Endpoint
/api/v1/route/revgeocoding

### Parameters
#### Query Parameters
- **lat** (string) - Required - Latitude coordinate in decimal degrees (e.g., 9.02152).
- **lon** (string) - Required - Longitude coordinate in decimal degrees.

### Response
#### Success Response (200)
- **msg** (string) - Status message (e.g., 'ok').
- **data** (array) - A list of places matching the query.

#### Response Example
{
  "msg": "ok",
  "data": [
    {
      "id": 103566,
      "name": "Welkite",
      "latitude": 8.992,
      "longitude": 38.774,
      "Country": "ethiopia",
      "City": "addis ababa",
      "type": "city",
      "details": "{}"
    }
  ]
}
```

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

### GET /api/route/tss

Source: https://docs.gebeta.app/gebeta-api.openapi.json

Solves a Traveling Salesman Problem (TSP) using the provided coordinates and returns the optimal visiting order, route geometry, and total distance and time.

```APIDOC
## GET /api/route/tss

### Description
Solves a Traveling Salesman Problem (TSP) using the coordinates provided and returns the most optimal visiting order, original order, route geometry, and total distance and time taken. The route starts and ends at the first coordinate.

### Method
GET

### Endpoint
/api/route/tss

### Parameters
#### Query Parameters
- **json** (string) - Required - A JSON-formatted string representing a list of geographic coordinates (longitude, latitude). The first coordinate is considered the start and end point of the round trip.
- **apiKey** (string) - Required - A valid API key for authentication and access control.

### Response
#### Success Response (200)
- **msg** (string) - A status or informational message.
- **bestorder** (array) - The optimal visiting order of the input coordinates including the return to the starting point.
- **timetaken** (number) - Total estimated travel time (in seconds) for the optimized route.
- **totalDistance** (number) - Total estimated travel distance (in meters) for the optimized route.
- **originalorder** (array) - The original order indices of the input coordinates.
- **direction** (array) - The geographical path (route geometry) of the optimized trip. Each element is a [longitude, latitude] pair.

#### Response Example
{
  "msg": "Optimization completed successfully",
  "bestorder": [0, 2, 1, 0],
  "timetaken": 10840.284,
  "totalDistance": 32520.854,
  "originalorder": [0, 1, 2],
  "direction": [
    [8.98755168914795, 38.764892578125],
    [8.987594604492188, 38.76495361328125],
    [8.987668991088867, 38.76502990722656]
  ]
}
```

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

### GebetaMaps.init

Source: https://docs.gebeta.app/docs/tiles/js

Initializes a new map instance with authentication and configuration options.

```APIDOC
## GebetaMaps.init

### Description
Initializes the map within a specified DOM container and sets initial view properties.

### Parameters
- **container** (string|HTMLElement) - Required - The DOM element or ID where the map will be rendered.
- **center** (array) - Optional - Initial map center coordinates as [lng, lat]. Defaults to Addis Ababa.
- **zoom** (number) - Optional - Initial zoom level.
- **navigationControl** (boolean) - Optional - Whether to display zoom and compass controls.
- **style** (string) - Optional - The map style to apply (e.g., STANDARD, SATELLITE, TERRAIN).
```

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

### Initialize a Basic Map

Source: https://docs.gebeta.app/docs/tiles/js

Initializes the GebetaMaps instance with authentication credentials and basic configuration options.

```javascript
import { GebetaMaps } from '@gebeta/js';
 
const gebetaMap = new GebetaMaps({
  auth: { accessToken, refreshToken }
});
 
const map = gebetaMap.init({
  container: 'map',           // DOM element ID or HTMLElement
  center: [38.7685, 9.0161],  // [lng, lat] — defaults to Addis Ababa
  zoom: 12,
  navigationControl: true,    // adds zoom/compass controls
});
```

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

### Use Access Token

Source: https://docs.gebeta.app/authentication

Include the access token in the Authorization header for subsequent API requests.

```bash
curl -X GET https://mapapi.gebeta.app/api/v1/route?origin=...&destination=... \
-H "Authorization: Bearer <access_token>"
```

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

### Perform a basic ONM API request via cURL

Source: https://docs.gebeta.app/docs/onm

Use this command to initiate a request to the ONM API endpoint.

```bash
curl https://mapapi.gebeta.app/api/route/onm/?json=[]&origin={}&apiKey={}
```

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

### WebSocket Connection and Authentication

Source: https://docs.gebeta.app/docs/tracking

Establishes a connection to the tracking server and authenticates the client session.

```APIDOC
## WebSocket Connection

### Endpoint
`wss://track.gebeta.app/v1/track`

### Authentication
Clients must send an `authenticate` action message immediately after opening the connection.

### Request Example
{
  "action": "authenticate",
  "payload": {
    "user_id": "string",
    "role": "driver | office",
    "token": "<JWT_TOKEN>"
  }
}
```

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

### Configure Map Styles

Source: https://docs.gebeta.app/docs/tiles/js

Sets the visual style of the map using predefined constants from the Gebeta API.

```javascript
import { API } from '@gebeta/api';
 
gebetaMap.init({
  container: 'map',
  style: API.Map.Constants.MAP_STYLES.STANDARD, // default
  // style: API.Map.Constants.MAP_STYLES.SATELLITE,
  // style: API.Map.Constants.MAP_STYLES.TERRAIN,
});
```

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

### GET https://mapapi.gebeta.app/v2/search/reverse-geocoding

Source: https://docs.gebeta.app/docs/geocoding/geocoding-reverse

Retrieve geographic features and address details for a specific set of latitude and longitude coordinates.

```APIDOC
## GET https://mapapi.gebeta.app/v2/search/reverse-geocoding

### Description
The reverse geocoding query type allows you to look up a pair of coordinates and returns the geographic features at that location.

### Method
GET

### Endpoint
https://mapapi.gebeta.app/v2/search/reverse-geocoding?lon={longitude}&lat={latitude}

### Parameters
#### Query Parameters
- **lat** (number) - Required - The latitude decimal value from the geographic coordinate. Range: -90 to 90.
- **lon** (number) - Required - The longitude decimal value from the geographic coordinate. Range: -180 to 180.
- **apiKey** (string) - Required - A valid Gebeta API access token. Can also be supplied in the HTTP request as an Authorization: Bearer <apiKey> header.
- **size** (integer) - Optional - Specify the maximum number of results to return. Default: 1. Allowed range: 1 to 5.
- **category** (string) - Optional - Filter results to include only a subset of feature categories. Comma-separated list of category terms.

### Request Example
curl "https://mapapi.gebeta.app/v2/search/reverse-geocoding?lat=9.0192&lon=38.7578&apiKey=YOUR_API_KEY"

### Response
#### Success Response (200)
- **data** (object) - Contains the query results.

#### Response Example
{
  "data": {
    "query": "9.019200,38.757800",
    "results": [
      {
        "id": "way:123456",
        "name": "Bole Road",
        "display_name": "Bole Road, Addis Ababa, Ethiopia",
        "category": "highway",
        "location": {
          "lat": 9.019185,
          "lng": 38.757812
        },
        "address": {
          "city": "Addis Ababa",
          "country": "Ethiopia",
          "country_code": "ETH"
        }
      }
    ]
  }
}
```

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

### Geocoding with Gebeta Map API

Source: https://docs.gebeta.app/

Initializes a geocoding request using a location name and an API key.

```typescript
import { geocoding } from 'gebetamap';
let name = "kotebe 02";
let apiKey = "";
const geo = await geocoding(name, apiKey)
```

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

### Authenticate and Request Routes with Python

Source: https://docs.gebeta.app/authentication

Uses requests to exchange client and server tokens for access tokens, perform authorized API calls, and refresh tokens upon expiration.

```python
import requests

BASE_URL = "https://mapapi.gebeta.app/api/v1"

CLIENT_TOKEN = "your_client_token"
SERVER_TOKEN = "your_server_token"

# 1. Exchange service account credentials for access tokens
auth_response = requests.post(
    f"{BASE_URL}/external/auth",
    json={
        "client_token": CLIENT_TOKEN,
        "server_token": SERVER_TOKEN
    }
)

auth_data = auth_response.json()["data"]

access_token = auth_data["accessToken"]
refresh_token = auth_data["refreshToken"]

print("Access Token:", access_token)

# 2. Use access token to call APIs
route_response = requests.get(
    f"{BASE_URL}/route",
    headers={
        "Authorization": f"Bearer {access_token}"
    },
    params={
        "origin": "9.0222,38.7469",
        "destination": "9.0500,38.7500"
    }
)

print(route_response.json())

# 3. Refresh token usage (when access token expires)
refresh_response = requests.post(
    f"{BASE_URL}/external/refresh",
    json={
        "refresh_token": refresh_token
    }
)

new_access_token = refresh_response.json()["data"]["accessToken"]
print("New Access Token:", new_access_token)
```

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

### Send a POST request to the VRP API

Source: https://docs.gebeta.app/docs/vrp

Use this command to send a structured JSON payload containing vehicle, depot, and customer information for route optimization.

```bash
curl --request POST \
--url 'https://docs.gebeta.app/api/optimized-trip?apiKey={your-api-key}' \
--header 'Content-Type: application/json' \
--data '{
  "vehicles": [
    {
      "vehicle_id": 1,
      "current_location": [8.989022, 38.79036],
      "capacity": 10,
      "max_distance": 100
    },
    {
      "vehicle_id": 2,
      "current_location": [9.03045, 38.76530],
      "capacity": 8,
      "max_distance": 120
    }
  ],
  "depots": [
    {
      "depot_id": 1,
      "location": [8.989022, 38.79036]
    },
    {
      "depot_id": 2,
      "location": [9.05000, 38.78000]
    }
  ],
  "customers": [
    {
      "customer_id": 1,
      "location": [9.02000, 38.77000],
      "demand": 3
    },
    {
      "customer_id": 2,
      "location": [9.03500, 38.75000],
      "demand": 4
    },
    {
      "customer_id": 3,
      "location": [9.01000, 38.76000],
      "demand": 5
    }
  ]
}'
```

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

### Driver WebSocket Implementation

Source: https://docs.gebeta.app/docs/tracking

Authenticate the connection and send periodic location updates to the tracking server.

```javascript
const WebSocket = require("ws");
const ws = new WebSocket("wss://track.gebeta.app/v1/track");
 
ws.on("open", () => {
  ws.send(JSON.stringify({
    action: "authenticate",
    payload: {
      user_id: "DR_1",
      role: "driver",
      token: "<JWT_TOKEN>"
    }
  }));
 
  setInterval(() => {
    ws.send(JSON.stringify({
      action: "driver_location",
      id: "DR_1",
      payload: {
        lat: 9.01 + Math.random() * 0.01,
        lng: 38.70 + Math.random() * 0.01,
        speed: 12,
        bearing: 90
      }
    }));
  }, 3000);
});
```

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

### Map Matching API Usage

Source: https://docs.gebeta.app/docs/map-matching

Basic structure for a map matching request using the API endpoint.

```bash
curl https://mapapi.gebeta.app/api/route/matching/?path=[{lat,lng},{lat,lng}]&apiKey={your-api-key}&radius=1
```

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

### authenticate

Source: https://docs.gebeta.app/docs/tracking

Authenticates a client connection to the tracking service.

```APIDOC
## authenticate

### Description
Authenticates the client connection using a user ID, role, and JWT token.

### Parameters
- **user_id** (string) - Required - Unique identifier of the user
- **role** (string) - Required - 'driver' or 'office'
- **token** (string) - Required - Valid JWT access token

### Request Example
{
  "action": "authenticate",
  "payload": {
    "user_id": "DR_1",
    "role": "driver",
    "token": "<JWT_TOKEN>"
  }
}
```

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

### GET https://mapapi.gebeta.app/v2/search/geocode

Source: https://docs.gebeta.app/docs/geocoding/geocoding-forward

Look up a location using a string of search text to retrieve its coordinates, standardized address, and geographic context.

```APIDOC
## GET https://mapapi.gebeta.app/v2/search/geocode

### Description
The forward geocoding query type allows you to look up a location using a string of search text and returns its coordinates, standardized address, and geographic context.

### Method
GET

### Endpoint
https://mapapi.gebeta.app/v2/search/geocode

### Parameters
#### Query Parameters
- **query** (string) - Required - The feature you are trying to look up (e.g., address, city, POI). Must be a URL-encoded string.
- **apiKey** (string) - Required - A valid Gebeta API access token. Can also be supplied in the HTTP request as an `Authorization: Bearer <apiKey>` header.
- **autocomplete** (boolean) - Optional - Specify whether to return autocomplete results (true, default) or not (false).
- **bbox** (string) - Optional - Limit results to only those contained within the supplied bounding box (minLng,minLat,maxLng,maxLat).
- **country** (string) - Optional - Limit results to one or more countries using ISO country codes.
- **language** (string) - Optional - Set the language of the text supplied in responses.
- **limit** (integer) - Optional - Specify the maximum number of results to return (1 to 10).
- **proximity** (string) - Optional - Bias the response to favor results closer to a location (lng,lat) or 'ip'.
- **category** (string) - Optional - Filter results to include only a subset of feature categories.

### Request Example
curl "https://mapapi.gebeta.app/v2/search/geocode?query=Bole+Road&apiKey=YOUR_API_KEY"

### Response
#### Success Response (200)
- **data** (object) - The container for the query results.

#### Response Example
{
  "data": {
    "query": "Bole Road",
    "results": [
      {
        "id": "way:123456",
        "name": "Bole Road",
        "display_name": "Bole Road, Addis Ababa, Ethiopia",
        "category": "highway",
        "location": {
          "lat": 9.019185,
          "lng": 38.757812
        },
        "address": {
          "city": "Addis Ababa",
          "country": "Ethiopia",
          "country_code": "ETH"
        }
      }
    ]
  }
}
```

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

### Fetch ONM API route data using JavaScript

Source: https://docs.gebeta.app/docs/onm

Use the fetch API to retrieve route information and log the response to the console.

```javascript
fetch('https://mapapi.gebeta.app/api/route/onm/?json=[8.989022,38.79036;9.03045,38.76530]&origin={origin-latitude,origin-longitude}&apiKey={your-api-key}')
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));
```

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

### Request Directions via cURL

Source: https://docs.gebeta.app/docs/direction

Basic cURL command structure for querying the Directions API endpoint.

```bash
curl https://mapapi.gebeta.app/api/route/direction/?origin={${origin.lat},${origin.lng}}&destination={${destination.lat},${destination.lng}}${waypointsString}&apiKey=${token.token}
```

```bash
curl "curl https://mapapi.gebeta.app/api/route/direction/?origin={${origin.lat},${origin.lng}}&destination={${destination.lat},${destination.lng}}${waypointsString}&apiKey=${token.token}"
```

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

### Generate Access Token

Source: https://docs.gebeta.app/authentication

Request a short-lived access token by providing the client and server tokens to the authentication endpoint.

```bash
curl --location --request POST 'https://mapapi.gebeta.app/api/v1/external/auth' \
--header 'Content-Type: application/json' \
--data-raw '{
  "client_token": "<client_token>",
  "server_token": "<server_token>"
}'
```

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

### Authenticate Message Structure

Source: https://docs.gebeta.app/docs/tracking

Required message format for client authentication immediately after connection.

```json
{
  "action": "authenticate",
  "payload": {
    "user_id": "DR_1",
    "role": "driver",
    "token": "<JWT_TOKEN>"
  }
}
```

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

### subscribe

Source: https://docs.gebeta.app/docs/tracking

Allows office clients to subscribe to driver location updates.

```APIDOC
## subscribe

### Description
Offices can subscribe to specific drivers or all drivers within their company to receive real-time location updates.

### Parameters
- **entity** (string) - The target to subscribe to (e.g., 'driver:DR_1' or 'company:drivers')

### Request Example
{
  "action": "subscribe",
  "entity": "driver:DR_1"
}
```

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

### POST /optimize-routes

Source: https://docs.gebeta.app/gebeta-api.openapi.json

Submits delivery data including vehicles, customers, and depots to calculate optimized routes for drivers.

```APIDOC
## POST /optimize-routes

### Description
Calculates optimized delivery routes based on provided vehicle, customer, and depot information.

### Method
POST

### Endpoint
/optimize-routes

### Request Body
- **vehicles** (array) - Required - List of vehicles available for delivery.
- **customers** (array) - Required - List of customers requesting deliveries.
- **depots** (array) - Required - List of depot locations where deliveries originate.

### Response
#### Success Response (200)
- **routes** (array) - List of optimized delivery routes for each driver, including assigned customers and depot details.
```

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

### GET /api/v1/route/getOwnedNearby

Source: https://docs.gebeta.app/gebeta-api.openapi.json

Performs reverse geocoding to retrieve nearby locations owned or managed by the service provider, based on geographic coordinates. Supports filtering by place type and level of detail.

```APIDOC
## GET /api/v1/route/getOwnedNearby

### Description
Performs reverse geocoding to retrieve nearby locations owned or managed by the service provider, based on geographic coordinates. Supports filtering by place type and level of detail.

### Method
GET

### Endpoint
/api/v1/route/getOwnedNearby

### Parameters
#### Query Parameters
- **lat** (string) - Required - Latitude of the location to reverse geocode.
- **lon** (string) - Required - Longitude coordinate in decimal degrees (e.g., 38.80131).
- **apiKey** (string) - Required - API key for authenticating the request.

### Response
#### Success Response (200)
- **msg** (string) - Status message (e.g., 'ok').
- **data** (array) - List of places corresponding to the provided coordinates.

#### Response Example
{
  "msg": "ok",
  "data": [
    {
      "name": "test",
      "latitude": 10,
      "longitude": 10,
      "Country": "test",
      "City": "test",
      "type": "test"
    },
    {
      "name": "test",
      "latitude": 10.1,
      "longitude": 10.1,
      "Country": "test",
      "City": "test",
      "type": "test"
    }
  ]
}
```