Barikoi APIs

https://github.com/barikoi/barikoiapis
Admin
Official TypeScript/JavaScript SDK for Barikoi Location Services providing geocoding, reverse...
Tokens:25,898
Snippets:196
Trust Score:6.7
License:MIT
Update:6 months ago
Show doc for...
Tokens:
Raw
### Barikoi SDK Development Setup

Source: https://github.com/barikoi/barikoiapis/blob/main/DEVELOPER_GUIDE.md

Steps to set up the development environment for the Barikoi npm package, including dependency installation, code generation, building, testing, and type checking.

```bash
git clone https://github.com/barikoi/barikoi-npm-package.git
cd barikoi-npm-package
npm install
npm run codegen
npm run build
npm test
npm run check-types
npm run lint
```

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

### Quick Start with Barikoi Client

Source: https://github.com/barikoi/barikoiapis/blob/main/README.md

Initialize the Barikoi client with your API key and perform an autocomplete search. This example highlights TypeScript inference and basic usage.

```typescript
import { createBarikoiClient } from 'barikoiapis'

const barikoi = createBarikoiClient({
  apiKey: 'YOUR_BARIKOI_API_KEY',
})

// Full TypeScript inference - no type imports needed
const result = await barikoi.autocomplete({ q: 'Dhaka' })
const places = result.data?.places || []
```

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

### Install Barikoi TypeScript SDK

Source: https://github.com/barikoi/barikoiapis/blob/main/DEVELOPER_GUIDE.md

Install the Barikoi TypeScript SDK using npm. Ensure you have Node.js and npm installed.

```bash
npm install barikoiapis
```

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

### Install and Use Node.js LTS

Source: https://github.com/barikoi/barikoiapis/blob/main/DEVELOPER_GUIDE.md

Instructions for installing and using Node.js version 20 LTS with nvm (Node Version Manager).

```bash
# Install and use Node 20 LTS
nvm install 20
nvm use 20
```

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

### Install Dependencies and Generate API Client

Source: https://github.com/barikoi/barikoiapis/blob/main/DEVELOPER_GUIDE.md

Commands to install project dependencies and regenerate the API client as part of the development workflow.

```bash
npm install
npm run codegen
```

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

### Install Barikoi SDK

Source: https://context7.com/barikoi/barikoiapis/llms.txt

Use npm or yarn to add the package to your project.

```bash
npm install barikoiapis
# or
yarn add barikoiapis
```

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

### Install Barikoi APIs via yarn

Source: https://github.com/barikoi/barikoiapis/blob/main/README.md

Install the Barikoi APIs SDK using yarn for use in your project.

```bash
yarn add barikoiapis
```

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

### Barikoi SDK CDN Usage Example

Source: https://github.com/barikoi/barikoiapis/blob/main/README.md

Example demonstrating how to use the Barikoi SDK in a vanilla JavaScript application loaded via CDN, including client creation and a search function.

```html
<!DOCTYPE html>
<html>
  <head>
    <title>Barikoi SDK Example</title>
  </head>
  <body>
    <button onclick="searchLocation()">Search Dhaka</button>
    <pre id="result"></pre>

    <!-- Load Barikoi SDK -->
    <script src="https://unpkg.com/barikoiapis@latest/dist/iife/index.js"></script>

    <script>
      // Global variable: barikoiapis
      const client = barikoiapis.createBarikoiClient({
        apiKey: 'YOUR_BARIKOI_API_KEY',
      })

      async function searchLocation() {
        try {
          const result = await client.autocomplete({ q: 'Dhaka' })
          document.getElementById('result').textContent = JSON.stringify(result.data, null, 2)
        } catch (error) {
          console.error('Error:', error)
        }
      }
    </script>
  </body>
</html>
```

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

### Refactor API Method Examples

Source: https://github.com/barikoi/barikoiapis/blob/main/docs/barikoi-sdk-migration-guide.md

Comparison of current verbose examples versus the target clean format.

```typescript
const searchPlaces = async (query: string) => {
  const result = await barikoi.autocomplete({
    q: query,
    bangla: true
  })
  
  result.data?.places?.forEach(place => {
    console.log(place.address)
    console.log(place.address_bn)
    console.log(`${place.latitude}, ${place.longitude}`)
  })
}
```

```typescript
const result = await barikoi.autocomplete({
  q: 'Dhaka',
  bangla: true
})

const places = result.data?.places || []
```

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

### GET /details

Source: https://context7.com/barikoi/barikoiapis/llms.txt

Get detailed place information using a place code and session ID.

```APIDOC
## GET /details

### Description
Get detailed place information using a place code and session ID. Returns complete address and coordinates.

### Parameters
#### Query Parameters
- **place_code** (string) - Required - Unique code from search results
- **session_id** (string) - Required - Session ID from search results

### Response
#### Success Response (200)
- **place** (object) - Detailed place information including address, coordinates, and place_code
```

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

### Verify Node.js and npm Versions

Source: https://github.com/barikoi/barikoiapis/blob/main/DEVELOPER_GUIDE.md

Verify that Node.js and npm are installed and meet the minimum version requirements for the Barikoi SDK.

```bash
node --version
npm --version
```

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

### Set API Key Environment Variable

Source: https://github.com/barikoi/barikoiapis/blob/main/DEVELOPER_GUIDE.md

Example of how to set the BARIKOI_API_KEY in a .env file for local development and testing.

```bash
BARIKOI_API_KEY=your_api_key_here
```

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

### GET /placeDetails

Source: https://github.com/barikoi/barikoiapis/blob/main/README.md

Get detailed place information using a place code and session ID.

```APIDOC
## GET /placeDetails

### Description
Get detailed place information using a place code and session ID. Returns complete address and coordinates. Use after Search Place to fetch full location data.

### Query Parameters
- **place_code** (string) - Required - Place code from search place results
- **session_id** (string) - Required - Session ID from search place results

### Response
#### Success Response (200)
- **place** (object) - Detailed place information including address, latitude, and longitude
- **session_id** (string) - The session ID used
```

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

### GET /search

Source: https://context7.com/barikoi/barikoiapis/llms.txt

Search for places and get unique place codes with a session ID.

```APIDOC
## GET /search

### Description
Search for places and get unique place codes with a session ID. Each request generates a new session ID required for Place Details API.

### Parameters
#### Query Parameters
- **q** (string) - Required - Search query

### Response
#### Success Response (200)
- **session_id** (string) - Session ID for subsequent requests
- **places** (array) - List of matching places with address and place_code
```

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

### GET /autocomplete

Source: https://github.com/barikoi/barikoiapis/blob/main/README.md

Search for places with autocomplete suggestions, returning matching places with addresses in English and Bangla.

```APIDOC
## GET /autocomplete

### Description
Search for places with autocomplete suggestions. Returns matching places with addresses in English and Bangla, coordinates, and place details.

### Method
GET

### Endpoint
/autocomplete

### Parameters
#### Query Parameters
- **q** (string) - Required - Search query string
- **bangla** (boolean) - Optional - Include Bangla language fields

### Response
#### Success Response (200)
- **places** (Array) - List of matching places
- **status** (number) - API status code
```

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

### Route Overview API

Source: https://github.com/barikoi/barikoiapis/blob/main/README.md

Get route information between two points.

```APIDOC
## GET /route-overview

### Description
Get route information between two points.

### Method
GET

### Endpoint
/route-overview

### Query Parameters
- **origin_lat** (number) - Required - Latitude of the origin.
- **origin_lng** (number) - Required - Longitude of the origin.
- **destination_lat** (number) - Required - Latitude of the destination.
- **destination_lng** (number) - Required - Longitude of the destination.

### Request Example
```json
{
  "origin_lat": 23.7500,
  "origin_lng": 90.3900,
  "destination_lat": 23.8103,
  "destination_lng": 90.4125
}
```

### Response
#### Success Response (200)
- **distance** (number) - The total distance of the route in meters.
- **duration** (number) - The estimated duration of the route in seconds.

#### Response Example
```json
{
  "data": {
    "distance": 10000,
    "duration": 1200
  }
}
```
```

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

### GET /searchPlace

Source: https://github.com/barikoi/barikoiapis/blob/main/README.md

Search for places and get unique place codes with a session ID.

```APIDOC
## GET /searchPlace

### Description
Search for places and get unique place codes with a session ID. Returns matching places with addresses. Use for business search, landmark lookup, and location selection.

### Query Parameters
- **q** (string) - Required - Search query string

### Response
#### Success Response (200)
- **places** (array) - List of matching places with address and place_code
- **session_id** (string) - Session ID required for Place Details API
```

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

### Add New Convenience Method to BarikoiClient

Source: https://github.com/barikoi/barikoiapis/blob/main/DEVELOPER_GUIDE.md

Example of how to add a new convenience method to the BarikoiClient class. This method automatically injects the API key.

```typescript
/**
 * Example: Add a new convenience method
 */
async searchPlace(params: Omit<SearchPlaceData['query'], 'api_key'>) {
  return searchPlace({
    query: {
      ...params,
      api_key: this.apiKey,
    },
  })
}
```

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

### Get Route Overview

Source: https://github.com/barikoi/barikoiapis/blob/main/docs/barikoi-sdk-migration-guide.md

Retrieves route information between two points. Coordinates must be in 'longitude,latitude' format.

```typescript
const result = await barikoi.routeOverview(
  '90.4125,23.8103;90.4000,23.8000',
  { geometries: 'geojson' }
)

const route = result.data?.routes?.[0]
const distanceKm = route.distance / 1000
const durationMin = route.duration / 60
```

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

### Calculate Route API

Source: https://github.com/barikoi/barikoiapis/blob/main/docs/barikoi-sdk-migration-guide.md

Get detailed route information with turn-by-turn navigation.

```APIDOC
## POST /calculate/route

### Description
Get detailed route with turn-by-turn navigation.

### Method
POST

### Endpoint
/calculate/route

### Query Parameters
- **profile** (string) - Optional - Specifies the routing profile. Allowed values: 'car', 'motorcycle', 'bike'.
- **country_code** (string) - Optional - Filter routes by country code.

### Request Body
- **data** (object) - Required - Contains start and destination points.
  - **start** (object) - Required - The starting point.
    - **latitude** (number) - Required - Latitude of the start point.
    - **longitude** (number) - Required - Longitude of the start point.
  - **destination** (object) - Required - The destination point.
    - **latitude** (number) - Required - Latitude of the destination point.
    - **longitude** (number) - Required - Longitude of the destination point.

### Request Example
```json
{
  "data": {
    "start": {
      "latitude": 23.8103,
      "longitude": 90.4125
    },
    "destination": {
      "latitude": 23.8000,
      "longitude": 90.4000
    }
  }
}
```

### Response
#### Success Response (200)
- **trip** (object) - Contains detailed trip information.
  - **status_message** (string) - Status message for the trip calculation.
  - **units** (string) - Units used for distance and duration.
  - **legs** (array) - An array of route legs, each containing summary and maneuvers.
    - **summary** (object) - Summary of the leg.
      - **time** (number) - Duration of the leg in seconds.
      - **length** (number) - Length of the leg in meters.
      - **has_toll** (boolean) - Indicates if the leg has tolls.
      - **has_highway** (boolean) - Indicates if the leg is on a highway.
    - **maneuvers** (array) - An array of turn-by-turn maneuvers for the leg.
      - **instruction** (string) - The navigation instruction.
      - **length** (number) - The length of the maneuver in meters.
      - **time** (number) - The time to complete the maneuver in seconds.
      - **street_names** (array) - An array of street names for the maneuver.

#### Response Example
```json
{
  "trip": {
    "status_message": "Trip calculated successfully",
    "units": "m,s",
    "legs": [
      {
        "summary": {
          "time": 180,
          "length": 1500,
          "has_toll": false,
          "has_highway": false
        },
        "maneuvers": [
          {
            "instruction": "Head north on Example Street",
            "length": 500,
            "time": 60,
            "street_names": ["Example Street"]
          }
        ]
      }
    ]
  },
  "status": 200
}
```
```

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

### Route Overview API

Source: https://github.com/barikoi/barikoiapis/blob/main/docs/barikoi-sdk-migration-guide.md

Get route information between two points. Coordinates must be in 'longitude,latitude' format.

```APIDOC
## GET /route/overview

### Description
Get route information between points.

### Method
GET

### Endpoint
/route/overview

### Query Parameters
- **coordinates** (string) - Required - Coordinates must be in "longitude,latitude" format, separated by a semicolon for multiple points.
- **geometries** (string) - Optional - Specifies the geometry format for the route. Allowed values: 'polyline', 'polyline6', 'geojson'.
- **profile** (string) - Optional - Specifies the routing profile. Allowed values: 'car', 'foot'.

### Request Example
```
GET /route/overview?coordinates=90.4125,23.8103;90.4000,23.8000&geometries=geojson&profile=car
```

### Response
#### Success Response (200)
- **routes** (array) - An array of route objects, each containing distance, duration, and geometry.
  - **distance** (number) - The total distance of the route in meters.
  - **duration** (number) - The total duration of the route in seconds.
  - **geometry** (object) - The geometric representation of the route (e.g., GeoJSON).
- **waypoints** (array) - An array of waypoint objects.
  - **location** (array) - The coordinates of the waypoint [longitude, latitude].
  - **name** (string) - The name of the waypoint.

#### Response Example
```json
{
  "code": "Ok",
  "routes": [
    {
      "distance": 1500,
      "duration": 180,
      "geometry": {
        "type": "LineString",
        "coordinates": [
          [90.4125, 23.8103],
          [90.4000, 23.8000]
        ]
      }
    }
  ],
  "waypoints": [
    {
      "location": [90.4125, 23.8103]
    },
    {
      "location": [90.4000, 23.8000]
    }
  ],
  "status": 200
}
```
```

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

### Place Details API

Source: https://github.com/barikoi/barikoiapis/blob/main/README.md

Get detailed information about a specific place.

```APIDOC
## GET /place-details

### Description
Get detailed information about a specific place.

### Method
GET

### Endpoint
/place-details

### Query Parameters
- **place_id** (string) - Required - The unique identifier of the place.

### Request Example
```json
{
  "place_id": "some_place_id"
}
```

### Response
#### Success Response (200)
- **place** (object) - Detailed information about the place.
  - **place_id** (string) - Unique identifier for the place.
  - **name** (string) - Name of the place.
  - **formatted_address** (string) - Formatted address of the place.
  - **geometry** (object) - Geographic coordinates.
    - **location** (object)
      - **lat** (number) - Latitude.
      - **lng** (number) - Longitude.
  - **types** (array) - Types of the place.
  - **opening_hours** (object) - Opening hours information.
  - **website** (string) - Website of the place.
  - **phone_number** (string) - Phone number of the place.

#### Response Example
```json
{
  "data": {
    "place": {
      "place_id": "some_place_id",
      "name": "Example Place",
      "formatted_address": "Example Address, Dhaka, Bangladesh",
      "geometry": {
        "location": {
          "lat": 23.8103,
          "lng": 90.4125
        }
      },
      "types": ["point_of_interest", "establishment"],
      "opening_hours": {
        "open_now": true
      },
      "website": "https://example.com",
      "phone_number": "+880123456789"
    }
  }
}
```
```

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

### GET /geocode

Source: https://context7.com/barikoi/barikoiapis/llms.txt

Validate and format addresses with completeness status and confidence score.

```APIDOC
## GET /geocode

### Description
Validate and format addresses with completeness status and confidence score. Returns standardized address format.

### Parameters
#### Query Parameters
- **q** (string) - Required - Address to geocode
- **district** (string) - Optional - Include district ('yes' | 'no')
- **bangla** (string) - Optional - Include Bangla address ('yes' | 'no')
- **thana** (string) - Optional - Include thana ('yes' | 'no')

### Response
#### Success Response (200)
- **given_address** (string) - The input address
- **fixed_address** (string) - The standardized address
- **address_status** (string) - 'complete' or 'incomplete'
- **confidence_score_percentage** (number) - Confidence score
```

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

### Get Route Overview with Barikoi API

Source: https://context7.com/barikoi/barikoiapis/llms.txt

Retrieves route geometry, distance, and duration between coordinates. Requires coordinates in 'longitude,latitude' format.

```typescript
import { createBarikoiClient } from 'barikoiapis'

const barikoi = createBarikoiClient({ apiKey: 'YOUR_API_KEY' })

const result = await barikoi.routeOverview({
  coordinates: '90.4125,23.8103;90.4000,23.8000',   // "lon,lat;lon,lat" format (required)
  geometries: 'geojson',                            // 'polyline' | 'polyline6' | 'geojson' (default: 'polyline')
  profile: 'car',                                   // 'car' | 'foot' (default: 'car')
})

// Access route data
const route = result.data?.routes?.[0]
if (route) {
  const distanceKm = (route.distance || 0) / 1000
  const durationMin = (route.duration || 0) / 60

  console.log({
    distance_km: distanceKm.toFixed(2),
    duration_min: durationMin.toFixed(2),
    geometry: route.geometry,
    waypoints: result.data?.waypoints,
  })

  // Access route legs
  route.legs?.forEach((leg, i) => {
    console.log(`Leg ${i + 1}: ${leg.distance}m, ${leg.duration}s`)
  })
}
```

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

### GET /routeOverview

Source: https://github.com/barikoi/barikoiapis/blob/main/README.md

Retrieves route information between geographical points, including geometry, distance, and duration.

```APIDOC
## GET /routeOverview

### Description
Get route information between geographical points. Returns route geometry, distance, duration, and waypoints in polyline or GeoJSON format.

### Parameters
#### Query Parameters
- **coordinates** (string) - Required - Coordinates in format "lon,lat;lon,lat"
- **geometries** (string) - Optional - Geometry format ('polyline', 'polyline6', 'geojson')
- **profile** (string) - Optional - Transportation profile ('car', 'foot')

### Response
#### Success Response (200)
- **code** (string) - Response code
- **routes** (array) - List of route objects containing geometry, legs, distance, and duration
- **waypoints** (array) - List of waypoints with location and metadata
```

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

### Validate Autocomplete API Response

Source: https://github.com/barikoi/barikoiapis/blob/main/DEVELOPER_GUIDE.md

Example test case for the autocomplete API, including response structure validation using Zod.

```typescript
describe('Autocomplete API', () => {
  const barikoi = createBarikoiClient({
    apiKey: process.env.BARIKOI_API_KEY!,
  })

  it('should validate response structure', async () => {
    const result = await barikoi.autocomplete({ q: 'Dhaka' })

    // Runtime validation using Zod
    await zAutocompleteResponse.parseAsync(result.data)
    expect(result.data?.places).toBeDefined()
  })
})
```

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

### Manage API Key

Source: https://github.com/barikoi/barikoiapis/blob/main/README.md

Demonstrates setting the API key during initialization, updating it at runtime, and retrieving the current key.

```typescript
// Set during initialization
const barikoi = createBarikoiClient({
  apiKey: 'YOUR_BARIKOI_API_KEY',
})

// Update API key at runtime
barikoi.setApiKey('new-api-key')

// Get current API key
const currentKey = barikoi.getApiKey()
```

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

### Initialize Barikoi Client

Source: https://github.com/barikoi/barikoiapis/blob/main/DEVELOPER_GUIDE.md

Create a client instance with basic or custom configuration options.

```typescript
import { createBarikoiClient } from 'barikoiapis'

// Basic usage
const barikoi = createBarikoiClient({
  apiKey: 'YOUR_BARIKOI_API_KEY',
})

// With custom configuration
const barikoi = createBarikoiClient({
  apiKey: 'YOUR_API_KEY',
  baseUrl: 'https://custom-endpoint',
  timeout: 15000, // 15 seconds
})
```

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

### Build Project

Source: https://github.com/barikoi/barikoiapis/blob/main/DEVELOPER_GUIDE.md

Run this command to generate the project's output files in the dist/ directory. This includes CommonJS and ES modules builds.

```bash
npm run build
```

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

### Initialize Barikoi Client

Source: https://context7.com/barikoi/barikoiapis/llms.txt

Create a client instance using your API key. Supports custom timeouts and base URLs for specific environment requirements.

```typescript
import { createBarikoiClient } from 'barikoiapis'

// Basic initialization
const barikoi = createBarikoiClient({
  apiKey: 'YOUR_BARIKOI_API_KEY',
})

// With custom configuration
const barikoiWithConfig = createBarikoiClient({
  apiKey: 'YOUR_BARIKOI_API_KEY',
  timeout: 60000, // 60 seconds (default: 30000ms)
  baseUrl: 'https://custom-endpoint.barikoi.xyz', // optional custom endpoint
})

// Runtime API key management
barikoi.setApiKey('new-api-key')
const currentKey = barikoi.getApiKey()
```

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

### Initialize Barikoi Client and Autocomplete

Source: https://github.com/barikoi/barikoiapis/blob/main/docs/barikoi-sdk-migration-guide.md

Initializes the Barikoi client with an API key and demonstrates a single API call for autocompletion.

```typescript
import { createBarikoiClient } from 'barikoiapis'

const barikoi = createBarikoiClient({
  apiKey: 'YOUR_BARIKOI_API_KEY'
})

const result = await barikoi.autocomplete({ q: 'Dhaka' })
```

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

### Implement Barikoi SDK via CDN

Source: https://context7.com/barikoi/barikoiapis/llms.txt

Load the SDK directly in the browser using a script tag. Access the client through the global barikoiapis object.

```html
<!DOCTYPE html>
<html>
<head>
  <title>Barikoi SDK Example</title>
</head>
<body>
  <button onclick="searchLocation()">Search Dhaka</button>
  <pre id="result"></pre>

  <!-- Load Barikoi SDK from CDN -->
  <script src="https://unpkg.com/barikoiapis@latest/dist/iife/index.js"></script>
  <!-- Or use jsDelivr: https://cdn.jsdelivr.net/npm/barikoiapis@latest/dist/iife/index.js -->

  <script>
    // Global variable: barikoiapis
    const client = barikoiapis.createBarikoiClient({
      apiKey: 'YOUR_BARIKOI_API_KEY',
    })

    async function searchLocation() {
      try {
        const result = await client.autocomplete({ q: 'Dhaka' })
        document.getElementById('result').textContent = JSON.stringify(result.data, null, 2)
      } catch (error) {
        console.error('Error:', error)
        document.getElementById('result').textContent = 'Error: ' + error.message
      }
    }
  </script>
</body>
</html>
```

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

### Configure Barikoi Client

Source: https://github.com/barikoi/barikoiapis/blob/main/docs/barikoi-sdk-migration-guide.md

Initialize the Barikoi client with API credentials and network settings, and manage configuration at runtime.

```typescript
import { createBarikoiClient } from 'barikoiapis'

const barikoi = createBarikoiClient({
  apiKey: process.env.BARIKOI_API_KEY,
  timeout: 10000,
  baseUrl: 'https://barikoi.xyz'
})

// Update at runtime
barikoi.setApiKey('new-key')
barikoi.setTimeout(15000)

// Get current values
barikoi.getApiKey()
barikoi.getTimeout()
```

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

### Run All Tests

Source: https://github.com/barikoi/barikoiapis/blob/main/DEVELOPER_GUIDE.md

Command to execute all tests defined in the project using npm.

```bash
# Run all tests
npm test
```

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

### GET /reverse-geocode

Source: https://github.com/barikoi/barikoiapis/blob/main/README.md

Convert coordinates to human-readable addresses with administrative details in English and Bangla.

```APIDOC
## GET /reverse-geocode

### Description
Convert coordinates to human-readable addresses with administrative details (district, division, thana) in English and Bangla.

### Method
GET

### Endpoint
/reverse-geocode

### Parameters
#### Query Parameters
- **longitude** (number) - Required - Longitude coordinate
- **latitude** (number) - Required - Latitude coordinate
- **country_code** (string) - Optional - Country code (ISO Alpha-2)
- **country** (boolean) - Optional
- **district** (boolean) - Optional
- **post_code** (boolean) - Optional
- **sub_district** (boolean) - Optional
- **union** (boolean) - Optional
- **pauroshova** (boolean) - Optional
- **location_type** (boolean) - Optional
- **division** (boolean) - Optional
- **address** (boolean) - Optional
- **area** (boolean) - Optional
- **bangla** (boolean) - Optional
- **thana** (boolean) - Optional

### Response
#### Success Response (200)
- **place** (object) - Address details
- **status** (number) - API status code
```

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

### Publish to npm

Source: https://github.com/barikoi/barikoiapis/blob/main/DEVELOPER_GUIDE.md

Steps to publish a new version of the package to npm. This includes updating the version, building the project, and then publishing.

```bash
# Update version
npm version patch|minor|major

# Build
npm run build

# Publish to npm
npm publish
```

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

### Load Barikoi SDK via unpkg CDN

Source: https://github.com/barikoi/barikoiapis/blob/main/README.md

Include the Barikoi SDK in your HTML file using a script tag from unpkg for vanilla JavaScript or quick prototyping.

```html
<script src="https://unpkg.com/barikoiapis@latest/dist/iife/index.js"></script>
```

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

### Test Changes

Source: https://github.com/barikoi/barikoiapis/blob/main/DEVELOPER_GUIDE.md

Commands to run tests, build the project, and lint the code to ensure changes meet quality standards.

```bash
npm test
npm run build
npm run lint
```

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

### Clone Repository

Source: https://github.com/barikoi/barikoiapis/blob/main/DEVELOPER_GUIDE.md

Command to clone the Barikoi NPM package repository from GitHub.

```bash
git clone https://github.com/barikoi/barikoi-npm-package.git
cd barikoi-npm-package
```

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

### Locate Generated Type Files

Source: https://github.com/barikoi/barikoiapis/blob/main/docs/barikoi-sdk-migration-guide.md

Common file paths for generated SDK types.

```bash
# Common locations
src/client/types.gen.ts
src/sdk.gen.ts
src/zod.gen.ts
```

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

### GET /nearby

Source: https://context7.com/barikoi/barikoiapis/llms.txt

Find places within a specified radius. Returns nearby locations sorted by distance with names, addresses, and coordinates.

```APIDOC
## GET /nearby

### Description
Find places within a specified radius. Returns nearby locations sorted by distance with names, addresses, and coordinates.

### Parameters
#### Query Parameters
- **latitude** (number) - Required - Latitude coordinate
- **longitude** (number) - Required - Longitude coordinate
- **radius** (number) - Optional - Search radius in kilometers (0.1-100, default: 0.5)
- **limit** (number) - Optional - Maximum results (1-100, default: 10)

### Response
#### Success Response (200)
- **places** (array) - List of nearby places including name, address, distance, coordinates, and metadata.
```

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

### Configure Vitest for Testing

Source: https://github.com/barikoi/barikoiapis/blob/main/DEVELOPER_GUIDE.md

Vitest configuration file setting global options, environment, timeouts, and coverage reporters.

```typescript
import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    globals: true,
    environment: 'node',
    testTimeout: 30000,
    hookTimeout: 30000,
    coverage: {
      provider: 'v8',
      reporter: ['text', 'json', 'html'],
      exclude: ['src/client/**', 'scripts/**'],
    },
  },
})
```

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

### Run Post-Generation Script

Source: https://github.com/barikoi/barikoiapis/blob/main/DEVELOPER_GUIDE.md

Combined command to first generate the API client and then run a post-processing script to fix TypeScript issues.

```bash
npm run codegen  # Runs: openapi-ts && node scripts/fix-generated.js
```

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

### Load Barikoi SDK via jsDelivr CDN

Source: https://github.com/barikoi/barikoiapis/blob/main/README.md

Include the Barikoi SDK in your HTML file using a script tag from jsDelivr for vanilla JavaScript or quick prototyping.

```html
<script src="https://cdn.jsdelivr.net/npm/barikoiapis@latest/dist/iife/index.js"></script>
```

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

### Manage API Key

Source: https://github.com/barikoi/barikoiapis/blob/main/DEVELOPER_GUIDE.md

Configure the API key using environment variables or update it at runtime.

```typescript
import { createBarikoiClient } from 'barikoiapis'

const barikoi = createBarikoiClient({
  apiKey: process.env.BARIKOI_API_KEY!,
})

// Update API key at runtime
barikoi.setApiKey('new-api-key')

// Get current API key
const currentKey = barikoi.getApiKey()
```

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

### Autocomplete Method Documentation Template

Source: https://github.com/barikoi/barikoiapis/blob/main/docs/barikoi-sdk-migration-guide.md

The complete template for the Autocomplete API method.

```markdown
### Autocomplete

Search for places with autocomplete suggestions.

```typescript
const result = await barikoi.autocomplete({
  q: 'Dhaka',
  bangla: true
})

const places = result.data?.places || []
```

<details>
<summary>Type Definitions</summary>

```typescript
type AutocompleteData = {
  query: {
    api_key: string
    q: string
    bangla?: boolean
  }
}

type AutocompleteResponse = {
  places?: Array<{
    id: string
    address: string
    address_bn?: string
    latitude: number
    longitude: number
    pType: string
    subType: string
  }>
  status?: number
}
```
</details>
```

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

### Define Custom Location Validation Schema

Source: https://github.com/barikoi/barikoiapis/blob/main/DEVELOPER_GUIDE.md

Example of defining a custom validation schema using Zod for location data, including name, coordinates, and radius.

```typescript
// src/lib/validation.ts
export const customLocationSchema = z.object({
  name: z.string(),
  coordinates: coordinatesSchema,
  radius: z.number().positive(),
})
```

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

### Run Specific Test File

Source: https://github.com/barikoi/barikoiapis/blob/main/DEVELOPER_GUIDE.md

Command to run a particular test file using npx and Vitest.

```bash
# Run specific test file
npx vitest run test/autocomplete.test.ts
```

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

### Generate API Client

Source: https://github.com/barikoi/barikoiapis/blob/main/DEVELOPER_GUIDE.md

Execute this command to regenerate the API client code from the OpenAPI specification. It involves running openapi-ts and a post-processing script.

```bash
npm run codegen
```

```bash
openapi-ts --input ./openapi/barikoi-api-spec.yaml --output ./src/client --client @hey-api/client-axios
node scripts/fix-generated.js
```

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

### Search for a location using Barikoi SDK

Source: https://github.com/barikoi/barikoiapis/blob/main/example/index.html

Initializes the Barikoi client with an API key and performs an autocomplete search for 'Dhaka'. Ensure the API key is valid and the DOM contains an element with the ID 'result'.

```javascript
// Global variable: barikoiapis const client = barikoiapis.createBarikoiClient({ apiKey: 'YOUR_BARIKOI_API_KEY', }) async function searchLocation() { try { const result = await client.autocomplete({ q: 'Dhaka' }) document.getElementById('result').textContent = JSON.stringify(result.data, null, 2) } catch (error) { console.error('Error:', error) } }
```

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

### Commit Changes

Source: https://github.com/barikoi/barikoiapis/blob/main/DEVELOPER_GUIDE.md

Commands to stage all changes, commit them with a descriptive message following conventional commits, and push to the remote repository.

```bash
git add .
git commit -m "feat: description of your changes"
git push origin feature/your-feature-name
```

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

### Standard API Method Pattern

Source: https://github.com/barikoi/barikoiapis/blob/main/docs/barikoi-sdk-migration-guide.md

The target structure for documenting API methods, including a direct SDK call and collapsible type definitions.

```typescript
const result = await barikoi.[methodName]({
  param: 'value'
})

const data = result.data
```

```typescript
type [MethodName]Data = {
  query: {
    param: type
  }
}

type [MethodName]Response = {
  data?: {
    field: type
  }
}
```

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

### Configure Git User Information

Source: https://github.com/barikoi/barikoiapis/blob/main/DEVELOPER_GUIDE.md

Set your Git username and email. This is required for the commit-msg hook to automatically add a Signed-off-by trailer.

```bash
git config user.name "Your Name"
git config user.email "your.email@example.com"
```

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

### Barikoi SDK Error Handling

Source: https://github.com/barikoi/barikoiapis/blob/main/docs/barikoi-sdk-migration-guide.md

Demonstrates how to handle different types of errors that can occur when using the Barikoi SDK, including validation, API, and timeout errors.

```typescript
import { ValidationError, BarikoiError, TimeoutError } from 'barikoiapis'

try {
  const result = await barikoi.autocomplete({ q: 'Dhaka' })
} catch (error) {
  if (error instanceof ValidationError) {
    // Invalid input parameters
    // error.field - parameter that failed
    // error.value - invalid value provided
  } else if (error instanceof BarikoiError) {
    // API returned error response
    // error.statusCode - HTTP status code
    // error.message - error description
  } else if (error instanceof TimeoutError) {
    // Request exceeded timeout limit
  }
}
```

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

### Fetch Route Overview in TypeScript

Source: https://github.com/barikoi/barikoiapis/blob/main/README.md

Retrieves route geometry, distance, and duration between points. Coordinates must be provided in 'longitude,latitude' format.

```typescript
const result = await barikoi.routeOverview({
  coordinates: '90.4125,23.8103;90.4000,23.8000',
  geometries: 'geojson',
})

const route = result.data?.routes?.[0]
const distanceKm = route.distance / 1000
const durationMin = route.duration / 60
```

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

### Configure OpenAPI Code Generation

Source: https://github.com/barikoi/barikoiapis/blob/main/DEVELOPER_GUIDE.md

Configuration file for openapi-ts, specifying input OpenAPI spec, output directory, and plugins for TypeScript, Zod validation, and SDK generation.

```typescript
import { defineConfig } from '@hey-api/openapi-ts'

export default defineConfig({
  input: './openapi/barikoi-api-spec.yaml',
  output: {
    path: './src/client',
  },
  plugins: [
    '@hey-api/typescript',
    {
      name: 'zod',
      dates: { local: true },
      metadata: true,
    },
    {
      name: '@hey-api/sdk',
      validator: {
        request: true,
        response: false,
      },
      asClass: false,
    },
  ],
})
```

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

### Create Feature Branch

Source: https://github.com/barikoi/barikoiapis/blob/main/DEVELOPER_GUIDE.md

Command to create a new Git branch for feature development.

```bash
git checkout -b feature/your-feature-name
```

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

### Perform Autocomplete Search

Source: https://context7.com/barikoi/barikoiapis/llms.txt

Retrieve place suggestions based on a query string. Results include both English and Bangla address fields.

```typescript
import { createBarikoiClient } from 'barikoiapis'

const barikoi = createBarikoiClient({ apiKey: 'YOUR_API_KEY' })

const result = await barikoi.autocomplete({
  q: 'Dhaka',       // Search query (required)
  bangla: true,     // Include Bangla language fields (optional, default: true)
})

// Access results
const places = result.data?.places || []
places.forEach(place => {
  console.log({
    id: place.id,
    address: place.address,
    address_bn: place.address_bn,      // Bangla address
    city: place.city,
    area: place.area,
    latitude: place.latitude,
    longitude: place.longitude,
    postCode: place.postCode,
    uCode: place.uCode,                // Unique code
  })
})
```

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

### Add Collapsible Type Definitions

Source: https://github.com/barikoi/barikoiapis/blob/main/docs/barikoi-sdk-migration-guide.md

Template for adding type definitions to documentation.

```markdown
<details>
<summary>Type Definitions</summary>

```typescript
[Copy exact types from your types.gen.ts file]
```
</details>
```

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

### Define Route Overview Types

Source: https://github.com/barikoi/barikoiapis/blob/main/README.md

TypeScript type definitions for the Route Overview request parameters and success response.

```typescript
export type RouteOverviewParams = {
  /** Coordinates in format "lon,lat;lon,lat" (required)
   * @format "lon,lat;lon,lat"
   * @example "90.4125,23.8103;90.3742,23.7461"
   */
  coordinates: string
  /** Geometry format for the route
   * @default 'polyline'
   */
  geometries?: 'polyline' | 'polyline6' | 'geojson'
  /** Transportation profile
   * @default 'car'
   */
  profile?: 'car' | 'foot'
}

export type RouteOverviewSuccess = {
    code?: string;
    routes?: Array<{
        /**
         * Encoded polyline (string) or GeoJSON (object)
         */
        geometry?: string | {
            [key: string]: unknown;
        };
        legs?: Array<{
            steps?: Array<{
                [key: string]: unknown;
            }>;
            /**
             * Distance in meters
             */
            distance?: number;
            /**
             * Duration in seconds
             */
            duration?: number;
            summary?: string;
            weight?: number;
        }>;
        distance?: number;
        duration?: number;
        weight_name?: string;
        weight?: number;
    }>;
    waypoints?: Array<{
        hint?: string;
        distance?: number;
        name?: string | null;
        location?: [
            number,
            number
        ];
    }>;
}
```

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

### API Key Management

Source: https://github.com/barikoi/barikoiapis/blob/main/README.md

Manage your API key for authentication.

```APIDOC
## API Key Configuration

### Setting API Key during Initialization
```typescript
const barikoi = createBarikoiClient({
  apiKey: 'YOUR_BARIKOI_API_KEY',
});
```

### Updating API Key at Runtime
```typescript
barikoi.setApiKey('new-api-key');
```

### Getting Current API Key
```typescript
const currentKey = barikoi.getApiKey();
```
```

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

### Place Details with TypeScript

Source: https://github.com/barikoi/barikoiapis/blob/main/docs/barikoi-sdk-migration-guide.md

Retrieves detailed information about a specific place using a place code and session ID.

```typescript
const details = await barikoi.placeDetails({
  place_code: 'BKOI2017',
  session_id: sessionId
})

const place = details.data?.place
```

```typescript
type PlaceDetailsData = {
  query: {
    api_key?: string
    place_code: string
    session_id: string
  }
}

type PlaceDetailsResponse = {
  place?: {
    address?: string
    place_code?: string
    latitude?: number
    longitude?: number
  }
  status?: number
}
```

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

### Route Overview

Source: https://context7.com/barikoi/barikoiapis/llms.txt

Retrieves route geometry, distance, and duration between geographical points.

```APIDOC
## GET /routeOverview

### Description
Get route information between geographical points. Returns route geometry, distance, duration, and waypoints in polyline or GeoJSON format.

### Parameters
#### Query Parameters
- **coordinates** (string) - Required - "lon,lat;lon,lat" format
- **geometries** (string) - Optional - 'polyline' | 'polyline6' | 'geojson' (default: 'polyline')
- **profile** (string) - Optional - 'car' | 'foot' (default: 'car')

### Response
#### Success Response (200)
- **distance** (number) - Distance in meters
- **duration** (number) - Duration in seconds
- **geometry** (string) - Route geometry
- **waypoints** (array) - List of waypoints
```

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

### Calculate Route with Turn-by-Turn Navigation

Source: https://github.com/barikoi/barikoiapis/blob/main/docs/barikoi-sdk-migration-guide.md

Calculates a detailed route with turn-by-turn navigation instructions. Supports different profiles like 'car', 'motorcycle', and 'bike'.

```typescript
const result = await barikoi.calculateRoute({
  data: { start: { latitude: 23.8103, longitude: 90.4125 },
    destination: { latitude: 23.8000, longitude: 90.4000 }
  }
}, {
  profile: 'car'
})

const trip = result.data?.trip
const legs = trip?.legs || []
```

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

### Implement TypeScript Support

Source: https://github.com/barikoi/barikoiapis/blob/main/docs/barikoi-sdk-migration-guide.md

Utilize auto-generated types for request parameters and API responses to ensure type safety.

```typescript
import type { AutocompleteData, AutocompleteResponse } from 'barikoiapis'

// Type-safe parameters
const params: Omit<AutocompleteData['query'], 'api_key'> = {
  q: 'Dhaka',
  bangla: true
}

// Type-safe response
const result: AutocompleteResponse = await barikoi.autocomplete(params)
```

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

### Run Tests in Watch Mode

Source: https://github.com/barikoi/barikoiapis/blob/main/DEVELOPER_GUIDE.md

Command to run tests in watch mode, automatically re-running tests when files change. Assumes the script is added to package.json.

```bash
# Watch mode (if you add this script to package.json)
npx vitest watch
```

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

### Remove Legacy Documentation Sections

Source: https://github.com/barikoi/barikoiapis/blob/main/docs/barikoi-sdk-migration-guide.md

Sections to be removed during the migration process.

```markdown
**Function:** `methodName(params)`

**Parameters:**
```typescript
{
  param: type  // description
}
```

**Returns:** Promise with...
```

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

### Regenerate API Client

Source: https://github.com/barikoi/barikoiapis/blob/main/DEVELOPER_GUIDE.md

Command to regenerate the API client using npm, typically after updating the OpenAPI specification.

```bash
# Regenerate API client after OpenAPI spec updates
npm run codegen
```

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

### Set Custom Base URL

Source: https://github.com/barikoi/barikoiapis/blob/main/README.md

Configures a custom base URL for the Barikoi API client.

```typescript
const barikoi = createBarikoiClient({
  apiKey: 'YOUR_KEY',
  baseUrl: 'https://custom-endpoint.barikoi.xyz',
})
```

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

### Configure Request Timeout

Source: https://github.com/barikoi/barikoiapis/blob/main/README.md

Sets the request timeout in milliseconds during client initialization. The default value is 30000ms.

```typescript
// Set timeout during initialization (in milliseconds)(default: 30000)
const barikoi = createBarikoiClient({
  apiKey: 'YOUR_KEY',
  timeout: 60000, // 60 seconds
})
```

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

### Place Details Type Definitions

Source: https://github.com/barikoi/barikoiapis/blob/main/README.md

TypeScript interfaces for place details request parameters and success responses.

```typescript
export type PlaceDetailsParams = {
  /** Place code from search place results (required)
   * @minLength 1
   */
  place_code: string
  /** Session ID from search place results (required)
   * @minLength 1
   */
  session_id: string
}

export type PlaceDetailsSuccess = {
    place?: {
        address?: string;
        place_code?: string;
        latitude?: string;
        longitude?: string;
    };
    session_id?: string;
    status?: number;
}
```

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

### Enable Debug Logging in TypeScript

Source: https://github.com/barikoi/barikoiapis/blob/main/DEVELOPER_GUIDE.md

Set the DEBUG environment variable to capture detailed logs and inspect the client configuration.

```typescript
// Set environment variable for debug logging
process.env.DEBUG = 'barikoi:*'

// Check generated client configuration
console.log(barikoi.getConfiguredClient().getConfig())
```

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

### Retrieve Place Details

Source: https://context7.com/barikoi/barikoiapis/llms.txt

Fetches comprehensive information for a specific location using a place code and session ID obtained from a search.

```typescript
import { createBarikoiClient } from 'barikoiapis'

const barikoi = createBarikoiClient({ apiKey: 'YOUR_API_KEY' })

// First, search for a place to get place_code and session_id
const searchResult = await barikoi.searchPlace({ q: 'barikoi' })
const sessionId = searchResult.data?.session_id
const placeCode = searchResult.data?.places?.[0]?.place_code

// Then get place details
if (placeCode && sessionId) {
  const details = await barikoi.placeDetails({
    place_code: placeCode,    // Required: from search results
    session_id: sessionId,    // Required: from search results
  })

  const place = details.data?.place
  if (place) {
    console.log({
      address: place.address,
      place_code: place.place_code,
      latitude: place.latitude,
      longitude: place.longitude,
    })
  }
}
```

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

### Route Overview Type Definitions

Source: https://github.com/barikoi/barikoiapis/blob/main/docs/barikoi-sdk-migration-guide.md

Defines the expected data structures for the route overview request and response.

```typescript
type RouteOverviewData = {
  path: {
    coordinates: string
  }
  query?: {
    api_key?: string
    geometries?: 'polyline' | 'polyline6' | 'geojson'
    profile?: 'car' | 'foot'
  }
}

type RouteOverviewResponse = {
  code?: string
  routes?: Array<{
    distance: number
    duration: number
    geometry: object
  }>
  waypoints?: Array<{
    location: [number, number]
    name?: string
  }>
  status?: number
}
```

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

### Search Place Type Definitions

Source: https://github.com/barikoi/barikoiapis/blob/main/README.md

TypeScript interfaces for search place request parameters and success responses.

```typescript
export type SearchPlaceParams = {
  /** Search query string (required)
   * @minLength 1
   */
  q: string
}

export type SearchPlaceSuccess = {
    places?: Array<{
        address?: string;
        place_code?: string;
    }>;
    session_id?: string;
    status?: number;
}
```

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

### POST /calculateRoute

Source: https://github.com/barikoi/barikoiapis/blob/main/README.md

Calculates detailed route information using the GraphHopper engine, including turn-by-turn instructions and elevation data.

```APIDOC
## POST /calculateRoute

### Description
Get detailed route information powered by GraphHopper routing engine. Returns comprehensive route data including path coordinates, distance, travel time, turn-by-turn instructions, and elevation data.

### Parameters
#### Request Body
- **start** (object) - Required - Start point coordinates (latitude, longitude)
- **destination** (object) - Required - Destination point coordinates (latitude, longitude)
- **type** (string) - Required - Route calculation type (default 'gh')
- **profile** (string) - Optional - Transportation profile ('car', 'motorcycle', 'bike')

### Response
#### Success Response (200)
- **hints** (object) - Routing engine hints
- **info** (object) - Metadata including copyrights and processing time
- **paths** (array) - Detailed path information including distance, time, points, and instructions
```
Tokens:
Raw