barikoiapis
Version:
Official TypeScript/JavaScript SDK for Barikoi Location Services
865 lines (719 loc) • 21.4 kB
Markdown
# Barikoi APIs - TypeScript/JavaScript SDK
[](https://www.npmjs.com/package/barikoiapis)
[](https://www.typescriptlang.org/)
[](https://opensource.org/licenses/MIT)
## Description
**Barikoi APIs** is the official TypeScript/JavaScript SDK for [Barikoi Location Services](https://barikoi.com). 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](https://developer.barikoi.com/register)
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:
```bash
npm install barikoiapis
```
Or using yarn:
```bash
yarn add barikoiapis
```
#### Option 2: CDN (For vanilla JavaScript)
Add the script tag to your HTML file:
```html
<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
```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 || []
```
## API Reference
### Quick Navigation
1. [Autocomplete](#autocomplete) - Search for places with autocomplete suggestions
2. [Reverse Geocoding](#reverse-geocoding) - Convert coordinates to addresses
3. [Nearby Places](#nearby-places) - Find places within a radius
4. [Geocode (Rupantor)](#geocode-rupantor) - Format and geocode addresses
5. [Search Place](#search-place) - Search for places with session management
6. [Place Details](#place-details) - Get detailed place information
7. [Route Overview](#route-overview) - Get route information between points
8. [Calculate Route](#calculate-route) - Detailed route with turn-by-turn instructions
9. [Snap to Road](#snap-to-road) - Find nearest point on road network
10. [Check Nearby](#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.
```typescript
const result = await barikoi.autocomplete({
q: 'Dhaka',
bangla: true,
})
const places = result.data?.places || []
```
---
<details>
<summary>Type Definitions</summary>
```typescript
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;
}
```
</details>
### 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.
```typescript
const result = await barikoi.reverseGeocode({
latitude: 23.8103,
longitude: 90.4125,
district: true,
bangla: true,
})
const place = result.data?.place
```
---
<details>
<summary>Type Definitions</summary>
```typescript
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;
}
```
</details>
### 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.
```typescript
const result = await barikoi.nearby({
latitude: 23.8103,
longitude: 90.4125,
radius: 1,
limit: 20,
})
const places = result.data?.places || []
```
---
<details>
<summary>Type Definitions</summary>
```typescript
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;
}
```
</details>
### 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.
```typescript
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
```
---
<details>
<summary>Type Definitions</summary>
```typescript
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;
}
```
</details>
### 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.
```typescript
const searchResult = await barikoi.searchPlace({ q: 'barikoi' })
const sessionId = searchResult.data?.session_id
const places = searchResult.data?.places || []
```
---
<details>
<summary>Type Definitions</summary>
```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;
}
```
</details>
### 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.
```typescript
const details = await barikoi.placeDetails({
place_code: 'BKOI2017',
session_id: sessionId,
})
const place = details.data?.place
```
---
<details>
<summary>Type Definitions</summary>
```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;
}
```
</details>
### 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.
```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
```
---
<details>
<summary>Type Definitions</summary>
```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
];
}>;
}
```
</details>
### 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.
```typescript
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
```
---
<details>
<summary>Type Definitions</summary>
```typescript
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
]>;
};
}>;
}
```
</details>
### 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.
```typescript
const result = await barikoi.snapToRoad({
point: '23.8103,90.4125', // Format: latitude,longitude
})
const snapped = result.data?.coordinates
const distance = result.data?.distance
```
---
<details>
<summary>Type Definitions</summary>
```typescript
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';
}
```
</details>
### 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.
```typescript
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'
```
---
<details>
<summary>Type Definitions</summary>
```typescript
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;
};
}
```
</details>
### API Key Management
```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()
```
### Timeout Configuration
```typescript
// Set timeout during initialization (in milliseconds)(default: 30000)
const barikoi = createBarikoiClient({
apiKey: 'YOUR_KEY',
timeout: 60000, // 60 seconds
})
```
### Custom Base URL
```typescript
const barikoi = createBarikoiClient({
apiKey: 'YOUR_KEY',
baseUrl: 'https://custom-endpoint.barikoi.xyz',
})
```
---
## Documentation
- [API Documentation](https://docs.barikoi.com/api) - Official Barikoi API docs
- [TypeScript Handbook](https://www.typescriptlang.org/docs/) - TypeScript documentation
- [Zod Documentation](https://zod.dev/) - Validation library docs
---
## Support Resources
- [Barikoi Website](https://www.barikoi.com/)
- [Developer Portal](https://developer.barikoi.com/)
- [Documentation](https://docs.barikoi.com/docs/maps-api)
- [Support Email](mailto:hello@barikoi.com)
---
## License
This library is licensed under the MIT License. See the [LICENSE](https://github.com/barikoi/barikoi-npm-package/blob/main/LICENSE) file for details.
<img src="https://docs.barikoi.com/img/barikoi-logo-black.svg" height="30" />