Skip to main content

Barikoi Laravel Package

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

License: MIT

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:

API ServiceDocumentation
Location Servicesdocs/location-api.md
- Reverse GeocodingConvert coordinates to address
- Geocoding (Rupantor)Convert address to coordinates
- AutocompletePlace suggestions
- Search PlaceText-based place search
- Place DetailsGet Place Details
- Nearby SearchFind places within radius
- Check NearbyCheck nearby location within a specified radius
- Snap to RoadCorrect GPS coordinates
Routing Servicesdocs/routing-api.md
- Route OverviewSimple route calculation
- Detailed RouteTurn-by-turn route with options

Usage​

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​

CodeMessage
400Validation Error: Invalid coordinates. Please check your input parameters.
401Authentication Failed: Invalid API key. Please verify your API key is correct.
404Not Found: Resource not found. The requested resource or endpoint does not exist.
429Rate Limit Exceeded: Too many requests. Please reduce the number of requests...
500Server Error: Internal Server Error. The Barikoi API is experiencing issues...

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​

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