README

A comprehensive Laravel package for integrating Barikoi API - Bangladesh's leading location data provider.

Features

• 🗺️ Location Services: Geocoding, Reverse Geocoding, Autocomplete, Place Search, Place Details, Nearby Places, Check nearby location within a specified radius, Snap to Road
• 🛣️ Routing: Calculate Detailed Route and Route Overview
• ⚠️ Error Handling: User-friendly exceptions with actionable error messages

Installation

composer require barikoi/barikoiapis

Configuration

1. Publish the configuration file:

php artisan vendor:publish --provider="Barikoi\BarikoiApis\BarikoiServiceProvider" --tag="config"

1. Add your Barikoi API credentials to .env:

BARIKOI_API_KEY=your_api_key_here

Get your API key from Barikoi.

Quick Start

use Barikoi\BarikoiApis\Facades\Barikoi;

// 1. Reverse geocoding with rich options
$options = [
    'country_code' => 'BD',
    'district' => true,
    'post_code' => true,
    'country' => true,
    'sub_district' => true,
    'union' => true,
    'pauroshova' => true,
    'location_type' => true,
    'division' => true,
    'address' => true,
    'area' => true,
    'bangla' => true,
    'thana' => true,
];
$reverse = Barikoi::reverseGeocode(90.3572, 23.8067, $options);

$autocomplete=Barikoi::autocomplete('barikoi', [
                'bangla'       => true,
                'city'         => 'dhaka',
                'sub_area'     => true,
                'sub_district' => true,
            ]);

// Geocode (Rupantor) - returns stdClass (object)
$geocoded = Barikoi::geocode('shawrapara');

// Search place by text
$places = Barikoi::searchPlace('Dhanmondi');

// Get place details by place_code - returns stdClass (object)
$placeDetails = Barikoi::placeDetails('BKOI2017', [
    'session_id' => '4c47157f-22d6-4689-abdf-c9f81eb43ae4'
]);

// Nearby search
$nearby = Barikoi::nearby(90.38305163, 23.87188719, 0.5, 2);

// Check nearby (geofence check)
$checkNearby = Barikoi::checkNearby(23.8067, 90.3572, 23.8070, 90.3575, 50);

// Snap to nearest road
$snapped = Barikoi::snapToRoad(23.8067, 90.3572);

// Detailed route between two points (returns stdClass object with "trip")
$route = Barikoi::calculateRoute([
    'start' => ['longitude' => 90.36558776260725, 'latitude' => 23.791645065364126],
    'destination' => ['longitude' => 90.3676300089066, 'latitude' => 23.784715477921843],
], [
    'type' => 'vh',           // 'vh' (motorcycle only) or 'gh' (all profiles)
    'profile' => 'motorcycle'  // 'bike', 'motorcycle', or 'car'
]);

// Simple route overview (returns stdClass object)
$overview = Barikoi::routeOverview([
    ['longitude' => 90.3572, 'latitude' => 23.8067],
    ['longitude' => 90.3680, 'latitude' => 23.8100],
], [
    'profile' => 'car',
    'geometries' => 'polyline',
]);

Documentation

📚 API Documentation

Complete documentation with parameters, conditions, and error handling for each API:

Usage

Using Facade (Recommended)

use Barikoi\BarikoiApis\Facades\Barikoi;

$reverse = Barikoi::reverseGeocode(90.3572, 23.8067); // returns stdClass (object)
$places = Barikoi::autocomplete('restaurant');

Error Handling

The package provides comprehensive error handling with user-friendly messages.

Exception Types

BarikoiValidationException - Validation errors (400)

• Invalid coordinates
• Missing parameters
• Invalid input values

BarikoiApiException - API errors (401, 404, 429, 500, etc.)

• 401: Invalid API key
• 404: Resource not found
• 429: Rate limit exceeded
• 500: Server error

Basic Usage

use Barikoi\BarikoiApis\Facades\Barikoi;
use Barikoi\BarikoiApis\Exceptions\BarikoiApiException;
use Barikoi\BarikoiApis\Exceptions\BarikoiValidationException;

try {
    $result = Barikoi::reverseGeocode(90.3572, 23.8067);

} catch (BarikoiValidationException $e) {
    // Handle validation errors (400)
    echo "Invalid input: " . $e->getMessage();

} catch (BarikoiApiException $e) {
    // Handle API errors (401, 404, 500, etc.)
    echo "API Error: " . $e->getMessage();
}

Error Messages

Getting Error Details

catch (BarikoiValidationException $e) {
    $message = $e->getMessage();              // User-friendly message
    $statusCode = $e->getCode();              // HTTP status code
}

See individual API documentation for specific error conditions and solutions.

Examples

Example 1: Get Address from GPS

public function getAddress(Request $request)
{
    try {
        $result = Barikoi::reverseGeocode(
            $request->longitude,
            $request->latitude,
            ['district' => true, 'bangla' => true]
        );

        return response()->json([
            'address' => $result->place->address,
            'district' => $result->place->district,
        ]);
    } catch (BarikoiApiException $e) {
        return response()->json(['error' => $e->getMessage()], $e->getCode());
    }
}

Example 2: Calculate Route

public function calculateRoute(Request $request)
{
    try {
        $route = Barikoi::calculateRoute([
            'start' => ['longitude' => $request->start_longitude, 'latitude' => $request->start_latitude],
            'destination' => ['longitude' => $request->destination_longitude, 'latitude' => $request->destination_latitude],
        ], [
            'type' => 'vh',
            'profile' => 'motorcycle'
        ]);

        return $route;
    } catch (BarikoiApiException $e) {
        return response()->json(['error' => 'Route calculation failed'], 500);
    }
}

API Reference

For detailed Barikoi API documentation, visit Barikoi API Documentation.

Changelog

See CHANGELOG.md for version history.

License

The MIT License (MIT). See License File for more information.

Credits

• Barikoi Technologies Limited
• Package developed for easy Laravel integration

Support

For issues or questions:

• Create an issue on GitHub
• Check the detailed API documentation in docs/ folder
• Contact support@barikoi.com for any support