barikoiapis

v2.0.2

Published

3 months ago

Official TypeScript/JavaScript SDK for Barikoi Location Services

Downloads

626

Barikoi APIs - TypeScript/JavaScript SDK

Description

Barikoi APIs is the official TypeScript/JavaScript SDK for Barikoi Location Services. Built on auto-generated code from the official OpenAPI specification, it provides a modern, type-safe interface for accessing a wide range of location-based services including search, geocoding, reverse geocoding, routing, and more.

This SDK is optimized for modern web applications including React, Next.js, Vue.js, and vanilla JavaScript projects.

Features

Auto-generated with @hey-api/openapi-ts - Always synchronized with OpenAPI specification
100% TypeScript Inference - Zero type imports required, full IntelliSense everywhere
Built-in Validation - Automatic Zod schema validation with clear error messages
Runtime API Key Management - Update API keys dynamically without reinitializing the client
Modern Async/await - Promise-based API with configurable timeouts
Custom Error Classes - ValidationError, BarikoiError, TimeoutError
Multiple Build Formats - ESM, CommonJS, IIFE, UMD and TypeScript declarations
Tree-shakeable - Import only what you need for optimal bundle size
CDN Ready - Use directly in browsers via unpkg or jsDelivr

Getting Started

Get Barikoi API Key

To access Barikoi's API services, you need to:

Register on Barikoi Developer Dashboard
Verify with your phone number
Claim your API key

Once registered, you'll be able to access the full suite of Barikoi API services. If you exceed the free usage limits, you'll need to subscribe to a paid plan.

Installation

Choose the installation method that best fits your project:

Option 1: Package Manager (Recommended)

Install the package using npm:

npm install barikoiapis

Or using yarn:

yarn add barikoiapis

Option 2: CDN (For vanilla JavaScript or quick prototyping)

Add the following script tags to your HTML file:

Using unpkg:

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

Using jsDelivr:

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

CDN Usage Example:

<!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>

Quick Start

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 || []

API Reference

Quick Navigation

Autocomplete - Search for places with autocomplete suggestions
Reverse Geocoding - Convert coordinates to addresses
Nearby Places - Find places within a radius
Geocode (Rupantor) - Format and geocode addresses
Search Place - Search for places with session management
Place Details - Get detailed place information
Route Overview - Get route information between points
Calculate Route - Detailed route with turn-by-turn instructions
Snap to Road - Find nearest point on road network
Check Nearby - Verify proximity within a radius

Autocomplete

Search for places with autocomplete suggestions. Returns matching places with addresses in English and Bangla, coordinates, and place details. Use for search boxes, address forms, and location pickers.

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

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

export type AutocompleteParams = {
  /** Search query string (required)
   * @minLength 1
   */
  q: string
  /** Include Bangla language fields
   * @default true
   */
  bangla?: boolean
}

export type AutocompleteSuccess = {
    places?: Array<{
        id?: number;
        longitude?: string | number;
        latitude?: string | number;
        address?: string;
        address_bn?: string;
        city?: string;
        city_bn?: string;
        area?: string;
        area_bn?: string;
        postCode?: string | number;
        pType?: string;
        uCode?: string;
    }>;
    status?: number;
}

Reverse Geocoding

Convert coordinates to human-readable addresses with administrative details (district, division, thana) in English and Bangla. Use for displaying user location, delivery addresses, and location tagging.

IMPORTANT: ⚠️ Enabling all optional parameters triggers multiple API calls, consuming more credits. Request only essential parameters.

const result = await barikoi.reverseGeocode({
  latitude: 23.8103,
  longitude: 90.4125,
  district: true,
  bangla: true,
})

const place = result.data?.place

export type ReverseGeocodeParams = {
  /** Longitude coordinate (required)
   * @minimum -180
   * @maximum 180
   */
  longitude: number
  /** Latitude coordinate (required)
   * @minimum -90
   * @maximum 90
   */
  latitude: number
  /** Country code (ISO Alpha-2 format, e.g., 'BD')
   * @default 'BD'
   */
  country_code?: string
  country?: boolean
  district?: boolean
  post_code?: boolean
  sub_district?: boolean
  union?: boolean
  pauroshova?: boolean
  location_type?: boolean
  division?: boolean
  address?: boolean
  area?: boolean
  bangla?: boolean
  thana?: boolean
}

export type ReverseGeocodeSuccess = {
    place?: {
        id?: string | number;
        distance_within_meters?: number;
        address?: string;
        area?: string;
        city?: string;
        postCode?: string;
        address_bn?: string;
        area_bn?: string;
        city_bn?: string;
        country?: string;
        division?: string;
        district?: string;
        sub_district?: string;
        pauroshova?: string | null;
        union?: string | null;
        location_type?: string;
        address_components?: {
            place_name?: string | null;
            house?: string | null;
            road?: string | null;
        } | null;
        area_components?: {
            area?: string | null;
            sub_area?: string | null;
        } | null;
        thana?: string;
        thana_bn?: string;
    };
    status?: number;
}

Nearby Places

Find places within a specified radius. Returns nearby locations sorted by distance with names, addresses, and coordinates. Perfect for "nearby stores", POI discovery, restaurant finders, and ATM locators.

const result = await barikoi.nearby({
  latitude: 23.8103,
  longitude: 90.4125,
  radius: 1,
  limit: 20,
})

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

export type NearbyParams = {
  /** Longitude coordinate (required)
   * @minimum -180
   * @maximum 180
   */
  longitude: number
  /** Latitude coordinate (required)
   * @minimum -90
   * @maximum 90
   */
  latitude: number
  /** Search radius in kilometers
   * @minimum 0.1
   * @maximum 100
   * @default 0.5
   */
  radius?: number
  /** Maximum number of results
   * @minimum 1
   * @maximum 100
   * @default 10
   */
  limit?: number
}

export type NearbySuccess = {
    places?: Array<{
        id?: number;
        name?: string;
        distance_in_meters?: string | number;
        longitude?: string;
        latitude?: string;
        pType?: string;
        Address?: string;
        area?: string;
        city?: string;
        postCode?: string;
        subType?: string;
        uCode?: string;
    }>;
    status?: number;
}

Geocode (Rupantor)

Validate and format addresses with completeness status and confidence score. Returns standardized address format. Use for checkout validation, delivery verification, and CRM data cleaning.

Note: Uses 2 API calls internally.

const result = await barikoi.geocode({
  q: 'house 23, road 5, mirpur dhaka',
  district: 'yes',
  bangla: 'yes',
})

const status = result.data?.address_status
const confidence = result.data?.confidence_score_percentage
const fixed = result.data?.fixed_address

export type GeocodeParams = {
  /** Address to geocode (required)
   * @minLength 1
   */
  q: string
  thana?: 'yes' | 'no'
  district?: 'yes' | 'no'
  bangla?: 'yes' | 'no'
}

export type GeocodeSuccess = {
    given_address?: string;
    fixed_address?: string;
    bangla_address?: string;
    address_status?: 'complete' | 'incomplete';
    geocoded_address?: {
        id?: string | number;
        Address?: string;
        address?: string;
        address_bn?: string;
        alternate_address?: string;
        area?: string;
        area_bn?: string;
        bounds?: string | null;
        business_name?: string | null;
        city?: string;
        city_bn?: string;
        created_at?: string;
        district?: string;
        geo_location?: Array<number>;
        holding_number?: string | null;
        latitude?: string;
        location?: string;
        location_shape?: string;
        longitude?: string;
        match_freq?: number;
        match_fuzzy?: number;
        matching_diff?: number;
        new_address?: string;
        pType?: string;
        place_code?: string;
        place_name?: string | null;
        popularity_ranking?: number;
        postCode?: string | number;
        postcode?: string | number;
        road_name_number?: string | null;
        score?: number;
        subType?: string;
        sub_area?: string | null;
        sub_district?: string;
        sub_type?: string;
        super_sub_area?: string | null;
        thana?: string;
        type?: string;
        uCode?: string;
        union?: string | number | null;
        unions?: string | number | null;
        updated_at?: string;
        user_id?: number;
    };
    confidence_score_percentage?: number;
    status?: number;
}

Search Place

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.

Note: Each request generates a new session ID required for Place Details API.

const searchResult = await barikoi.searchPlace({ q: 'barikoi' })

const sessionId = searchResult.data?.session_id
const places = searchResult.data?.places || []

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;
}

Place Details

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.

Note: Requires place code and session ID from Search Place request.

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

const place = details.data?.place

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;
}

Route Overview

Get route information between geographical points. Returns route geometry, distance, duration, and waypoints in polyline or GeoJSON format. Use for displaying routes, calculating distances, and showing ETAs.

Note: Coordinates must be in "longitude,latitude" format.

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

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
        ];
    }>;
}

Calculate Route

Get detailed route information powered by GraphHopper routing engine. Returns comprehensive route data including path coordinates, distance, travel time, turn-by-turn instructions with street names, and elevation data (ascend/descend). Use for GPS navigation apps, route planning, delivery optimization, and mapping applications requiring detailed routing information.

const result = await barikoi.calculateRoute({
  start: { latitude: 23.8103, longitude: 90.4125 },
  destination: { latitude: 23.8, longitude: 90.4 },
  type: 'gh',
  profile: 'car',
})

const hints = result.data?.hints
const paths = result.data?.paths

export type CalculateRouteParams = {
  /** Start point coordinates (required) */
  start: {
    /** Start latitude
     * @minimum -90
     * @maximum 90
     */
    latitude: number
    /** Start longitude
     * @minimum -180
     * @maximum 180
     */
    longitude: number
  }
  /** Destination point coordinates (required) */
  destination: {
    /** Destination latitude
     * @minimum -90
     * @maximum 90
     */
    latitude: number
    /** Destination longitude
     * @minimum -180
     * @maximum 180
     */
    longitude: number
  }
  /** Route calculation type
   * @default 'gh'
   */
  type: 'gh'
  /** Transportation profile */
  profile?: 'car' | 'motorcycle' | 'bike'
}

export type CalculateRouteSuccess = {
    hints?: {
        'visited_nodes.sum'?: number;
        'visited_nodes.average'?: number;
    };
    info?: {
        copyrights?: Array<string>;
        took?: number;
        road_data_timestamp?: string;
    };
    paths?: Array<{
        /**
         * Distance in meters
         */
        distance?: number;
        weight?: number;
        /**
         * Time in milliseconds
         */
        time?: number;
        transfers?: number;
        points_encoded?: boolean;
        bbox?: [
            number,
            number,
            number,
            number
        ];
        /**
         * GeoJSON LineString with route coordinates
         */
        points?: {
            type?: 'LineString';
            coordinates?: Array<[
                number,
                number
            ]>;
        };
        instructions?: Array<{
            distance?: number;
            heading?: number;
            sign?: number;
            interval?: [
                number,
                number
            ];
            text?: string;
            time?: number;
            street_name?: string;
        }>;
        legs?: Array<{
            [key: string]: unknown;
        }>;
        details?: Array<{
            [key: string]: unknown;
        }>;
        ascend?: number;
        descend?: number;
        snapped_waypoints?: {
            type?: 'LineString';
            coordinates?: Array<[
                number,
                number
            ]>;
        };
    }>;
}

Snap to Road

Find the nearest road point to given coordinates. Returns snapped coordinates and distance to road. Use for vehicle tracking, GPS trace alignment, and ride-sharing location accuracy.

const result = await barikoi.snapToRoad({
  point: '23.8103,90.4125', // Format: latitude,longitude
})

const snapped = result.data?.coordinates
const distance = result.data?.distance

export type SnapToRoadParams = {
  /** Point coordinates in format "latitude,longitude" (required)
   * @format "latitude,longitude"
   * @example "23.8103,90.4125"
   */
  point: string
}

export type SnapToRoadSuccess = {
    coordinates?: [
        number,
        number
    ];
    /**
     * Distance in meters
     */
    distance?: number;
    type?: 'Point';
}

Check Nearby

Verify if a location is within a specified radius. Returns "Inside geo fence" or "Outside geo fence" status. Perfect for delivery notifications, driver alerts, proximity triggers, and employee check-in from devices in HR applications.

const result = await barikoi.checkNearby({
  current_latitude: 23.8103,
  current_longitude: 90.4125,
  destination_latitude: 23.8,
  destination_longitude: 90.4,
  radius: 100,
})

const isInside = result.data?.message === 'Inside geo fence'

export type CheckNearbyParams = {
  /** Destination latitude coordinate (required)
   * @minimum -90
   * @maximum 90
   */
  destination_latitude: number
  /** Destination longitude coordinate (required)
   * @minimum -180
   * @maximum 180
   */
  destination_longitude: number
  /** Radius in meters (required)
   * @minimum 1
   * @maximum 1000
   */
  radius: number
  /** Current latitude coordinate (required)
   * @minimum -90
   * @maximum 90
   */
  current_latitude: number
  /** Current longitude coordinate (required)
   * @minimum -180
   * @maximum 180
   */
  current_longitude: number
}

export type CheckNearbySuccess = {
    message?: string;
    status?: number;
    data?: {
        id?: string;
        name?: string;
        radius?: string;
        latitude?: string;
        longitude?: string;
        user_id?: number;
    };
}

API Key Management

// 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()

Timeout Configuration

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

Custom Base URL

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

Documentation

API Documentation - Official Barikoi API docs
TypeScript Handbook - TypeScript documentation
Zod Documentation - Validation library docs

Support Resources

License

This library is licensed under the MIT License. See the LICENSE file for details.