barikoiapis

Official TypeScript/JavaScript SDK for Barikoi Location Services
8,103
vue typescript react openapi javascript maps autocomplete sdk nextjs type-safe routing geocoding api-client navigation mapping places
Install
npm install barikoiapis
Latest Version:2.0.3
License:MIT
Last Updated:Jul 9, 2026
Links: npm
Maintainer: barikoi

Barikoi APIs - TypeScript/JavaScript SDK

npm version TypeScript License: MIT

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:

  1. Register on Barikoi Developer Dashboard
  2. Verify with your phone number
  3. 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.

API Key Handling

The Barikoi API authenticates each request with an API key sent as a query parameter. In a browser the key is visible to end users, so keep the key server-side whenever possible (for example, point baseUrl at your own backend). The SDK prints a one-time warning if used directly in a browser without allowBrowser: true, which you can set when you've restricted the key by domain or are pointing baseUrl at a proxy.

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)

Add the script tag to your HTML file:

<script src="https://unpkg.com/barikoiapis@latest/dist/iife/index.js"></script>
<script>
  const client = barikoiapis.createBarikoiClient({
    apiKey: 'YOUR_BARIKOI_API_KEY',
    allowBrowser: true // suppresses the one-time browser warning
  })
</script>

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

  1. Autocomplete - Search for places with autocomplete suggestions
  2. Reverse Geocoding - Convert coordinates to addresses
  3. Nearby Places - Find places within a radius
  4. Geocode (Rupantor) - Format and geocode addresses
  5. Search Place - Search for places with session management
  6. Place Details - Get detailed place information
  7. Route Overview - Get route information between points
  8. Calculate Route - Detailed route with turn-by-turn instructions
  9. Snap to Road - Find nearest point on road network
  10. 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 || []
Type Definitions 
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
Type Definitions 
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 || []
Type Definitions 
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
Type Definitions 
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 || []
Type Definitions 
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
Type Definitions 
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
Type Definitions 
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
Type Definitions 
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
Type Definitions 
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'
Type Definitions 
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

Support Resources

License

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

Related Packages

vue3-address-autocomplete

Input component with embedded Google Places API Autocomplete functionality

5,719
address autocomplete maps places vue google vue 3 vue3
permix

Permix is a lightweight, framework-agnostic, type-safe permissions management li...

385,566 640
javascript nextjs react type-safe typescript vue access-control acl authorization frontend +7
paymid-sdk

A frontend SDK for Paymid payment processing

15,682
javascript react sdk vue frontend payment
silgi

The fastest end-to-end type-safe RPC framework for TypeScript — compiled pipelin...

29,920 35
nextjs openapi react type-safe typescript api client express h3 middleware +11
@poluru-labs/fetchwise

Type-safe Fetch HTTP client with retries, interceptors, validation, and multi-ho...

1,102 2
javascript nextjs react type-safe typescript vue angular api browser client +11

Version History

Version Released License
2.0.3 MIT
2.0.2 MIT
2.0.1 MIT
2.0.0 MIT
1.0.8 MIT