barikoiapis/README.md

Bangladeshi location data provider API library from barikoi.com

# Barikoi APIs Node.js Library

## Description

The Barikoi APIs Node.js library provides access to location-based data from [Barikoi](https://barikoi.com). It includes functionalities for autocomplete search, reverse geocoding, nearby places, and address conversion.

## Installation

To install the package, use npm:

```bash
npm install barikoiapis
```

## Usage

### Importing the Library

```typescript
import { autocomplete, reverseGeocode, nearby, rupantor } from 'barikoiapis';
```

### Autocomplete

**Function:** `autocomplete`

**Parameters:**

- `options` (object):
  - `q` (string): The search query for autocomplete.
  - `area` (string, optional): Specific area to filter results by.
  - `city` (string, optional): City to filter results by.
  - `bangla` (boolean, optional): If `true`, returns results in Bangla. Defaults to `false`.
  - `country_code` (string, optional): Country code to filter results by.
  - `post_office` (boolean, optional): If `true`, includes post office information.
  - `industrial` (boolean, optional): If `true`, includes industrial areas.

**Returns:** A Promise that resolves to an object with the following structure:

```
{
  "places": [
    {
      "id": number,
      "longitude": string,
      "latitude": string,
      "address": string,
      "city": string,
      "area": string,
      "postCode": number,
      "pType": string,
      "subType": string,
      "district": string,
      "uCode": string
    },
    ...
  ],
  "status": number
}

```

**Example:**

```typescript
const options = {
  q: 'Dhaka',
  city: 'Dhaka',
  bangla: true,
};

autocomplete(options)
  .then((results) => {
    console.log('Autocomplete results:', results);
  })
  .catch((error) => {
    console.error('Error:', error);
  });
```

### Reverse Geocoding

**Function:** `reverseGeocode`

**Parameters:**

- `options` (object):
  - `longitude` (number): Longitude of the location.
  - `latitude` (number): Latitude of the location.
  - `district` (boolean, optional): If `true`, includes district information.
  - `post_code` (boolean, optional): If `true`, includes postal code.
  - `country` (boolean, optional): If `true`, includes country information.
  - `country_code` (string, optional): Country code.
  - `sub_district` (boolean, optional): If `true`, includes sub-district information.
  - `union` (boolean, optional): If `true`, includes union information.
  - `pauroshova` (boolean, optional): If `true`, includes pauroshova information.
  - `location_type` (boolean, optional): If `true`, includes location type.
  - `division` (boolean, optional): If `true`, includes division information.
  - `address` (boolean, optional): If `true`, includes address information.
  - `area` (boolean, optional): If `true`, includes area information.
  - `bangla` (boolean, optional): If `true`, returns results in Bangla.

**Returns:** A Promise that resolves to an object with the following structure:

```
{
  "place":
{
  "id": number,
  "distance_within_meters": number,
  "address": string,
  "area": string,
  "city": string,
  "district": string (optional),
  "post_code": string (optional),
  "country": string (optional),
  "country_code": string (optional),
  "sub_district": string (optional),
  "union": string (optional),
  "pauroshova": string (optional),
  "location_type": string (optional),
  "division": string (optional)
},
   "status": number
}
```

**Example:**

```typescript
const options = {
  latitude: 23.8103,
  longitude: 90.4125,
  district: true,
  country: true,
  bangla: true,
};

reverseGeocode(options)
  .then((results) => {
    console.log('Reverse geocode results:', results);
  })
  .catch((error) => {
    console.error('Error:', error);
  });
```

### Nearby Places

**Function:** `nearby`

**Parameters:**

- `radius` (number): Radius in meters to search for nearby places.
- `limit` (number): Number of results to return.
- `options` (object):
  - `longitude` (number): Longitude of the location.
  - `latitude` (number): Latitude of the location.

**Returns:** A Promise that resolves to an object with the following structure:

```
{
  "places": [
    {
      "id": number,
      "name": string,
      "distance_in_meters": string,
      "longitude": string,
      "latitude": string,
      "city": string,
      "area": string,
      "ST_AsText(location)": string,
      "pType": string,
      "subType": string,
      "postCode": string,
      "Address": string,
      "uCode": string
    },
    ...
  ],
  "status": number
}
```

**Example:**

```typescript
const radius = 1000; // Radius in meters
const limit = 10; // Number of results to return
const options = {
  longitude: 90.4125,
  latitude: 23.8103,
};

nearby(radius, limit, options)
  .then((results) => {
    console.log('Nearby places:', results);
  })
  .catch((error) => {
    console.error('Error:', error);
  });
```

### Rupantor (Place Conversion)

**Function:** `rupantor`

**Parameters:**

- `options` (object):
  - `q` (string): The address to convert.
  - `thana` (string, optional): Thana to filter by.
  - `district` (string, optional): District to filter by.
  - `bangla` (boolean, optional): If `true`, returns the address in Bangla.

**Returns:** A Promise that resolves to an object with the following structure:

```
{
  "given_address": string,
  "fixed_address": string,
  "address_status": string,
  "geocoded_address": {
    "Address": string,
    "address_bn": string,
    "address_short": string,
    "area": string,
    "city": string,
    "district": string,
    "holding_number": string,
    "latitude": string,
    "longitude": string,
    "pType": string,
    "postCode": string,
    "road_name_number": string,
    "score": number,
    "sub_area": string,
    "super_sub_area": string (nullable),
    "thana": string,
    "uCode": string,
    "unions": string (nullable)
  },
  "confidence_score_percentage": number,
  "status": number
}
```

**Example:**

```typescript
const options = {
  q: 'Dhaka',
  thana: 'Dhaka Sadar',
  district: 'Dhaka',
  bangla: true,
};

rupantor(options)
  .then((result) => {
    console.log('Rupantor result:', result);
  })
  .catch((error) => {
    console.error('Error:', error);
  });
```

## API Documentation

### `autocomplete(options: AutocompleteOptions): Promise<{ places: AutocompleteResult[], status: number }>`

**Parameters:**

- `q` (string): Search query.
- `area` (string, optional): Area to filter by.
- `city` (string, optional): City to filter by.
- `bangla` (boolean, optional): Return results in Bangla.
- `country_code` (string, optional): Country code.
- `post_office` (boolean, optional): Include post office information.
- `industrial` (boolean, optional): Filter to include industrial areas.

**Returns:** Array of `AutocompleteResult` objects.

### `reverseGeocode(options: ReverseGeocodeOptions): Promise<{ place: ReverseGeocodeResult, status: number }>`

**Parameters:**

- `longitude` (number): Longitude.
- `latitude` (number): Latitude.
- `district` (boolean, optional): Include district information.
- `post_code` (boolean, optional): Include postal code.
- `country` (boolean, optional): Include country information.
- `country_code` (string, optional): Country code.
- `sub_district` (boolean, optional): Include sub-district information.
- `union` (boolean, optional): Include union information.
- `pauroshova` (boolean, optional): Include pauroshova information.
- `location_type` (boolean, optional): Include location type.
- `division` (boolean, optional): Include division information.
- `address` (boolean, optional): Include address information.
- `area` (boolean, optional): Include area information.
- `bangla` (boolean, optional): Return results in Bangla.

**Returns:** A Promise that resolves to an object containing:place (ReverseGeocodeResult):

- The result of the reverse geocoding request, which is a single location object.
- status (number): The HTTP status code of the response.

### `nearby(radius: number, limit: number, options: NearbyOptions): Promise<{ places: NearbyResult[], status: number }>`

**Parameters:**

- `radius` (number): Radius in meters.
- `limit` (number): Number of results.
- `options` (object):
  - `longitude` (number): Longitude.
  - `latitude` (number): Latitude.

**Returns:** Array of `NearbyResult` objects.

### `rupantor(options: RupantorOptions): Promise<{ given_address: string, fixed_address: string, address_status: string, geocoded_address: RupantorResult, confidence_score_percentage: number, status: number }>`

**Parameters:**

- `q` (string): Address to convert.
- `thana` (string, optional): Thana to filter by.
- `district` (string, optional): District to filter by.
- `bangla` (boolean, optional): Return address in Bangla.

**Returns:** `RupantorResult` object.

## Configuration

You can configure the API key and version using the following functions:

```typescript
import { setConfig, getConfig } from 'barikoiapis';

// Set configuration
setConfig({ apiKey: 'your_api_key', version: 'v2' });

// Get current configuration
const config = getConfig();
console.log('Current configuration:', config);
```

## Error Handling

All functions throw errors when requests fail. Ensure you handle errors using try-catch or promise rejection handling.

```typescript
try {
  const results = await autocomplete(options);
} catch (error) {
  console.error('Error:', error);
}
```

## License

This library is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

## Support

For any issues or questions, please contact [support@barikoi.com](mailto:support@barikoi.com).