README

A Laravel package wrapping the api.co.id Indonesia Regional API with a fluent query builder.

Installation

composer require aslammaududy/laravel-api-co-id

You can publish the config file with:

php artisan vendor:publish --tag="laravel-api-co-id-config"

Configuration

Add these to your .env:

API_CO_ID_API_KEY=your-api-key-here

Usage

Free Endpoints

use Aslam\ApiCoId\Facades\Indonesia;

// List all provinces
Indonesia::provinces()->get();

// Get a single province
Indonesia::province('11')->get();

// Get regencies of a province
Indonesia::province('11')->regencies()->get();

// Filter regencies by province code
Indonesia::regencies()->where('province_code', '11')->get();

// Filter with like operator
Indonesia::regencies()->where('name', 'like', '%Timur%')->get();

// Get districts of a regency
Indonesia::regencies()->where('name', 'like', '%Timur%')->first();
Indonesia::district('110101')->get();
Indonesia::district('110101')->villages()->get();

// List villages with filter
Indonesia::villages()->where('district_code', '110101')->get();
Indonesia::villages()->where('name', 'like', '%Jakarta%')->page(2)->get();

// Get a single village
Indonesia::village('1101011001')->get();

Pagination

// Paginate with 10 items per page
$paginator = Indonesia::provinces()->paginate(10);

// Paginate with filters
$paginator = Indonesia::villages()
    ->where('district_code', '110101')
    ->paginate(50);

// Access pagination methods
echo $paginator->currentPage();
echo $paginator->lastPage();
echo $paginator->total();
foreach ($paginator->items() as $item) {
    // ...
}

Single Result

$province = Indonesia::province('11')->first();
// Returns ?array - null if not found

$province = Indonesia::provinces()->where('name', 'Aceh')->first();

Paid Endpoints

// Search across all regions
Indonesia::search('Jakarta')->get();

// Look up postal code
Indonesia::postalCode('12345')->get();

Pricing

api.co.id uses a pay-as-you-go points system. You top up points, and each successful API call deducts points according to the endpoint's cost.

If your points run out, the API returns 402 Insufficient Balance or 403 Premium Required. The package throws an ApiException with the API's error message — no action needed, just top up your points.

Note: All endpoints are accessible regardless of your balance. The API itself decides whether you have enough points. There's no need to toggle any "premium mode" setting.

Fluent Chaining

All configuration methods return $this, enabling method chaining:

Indonesia::villages()
    ->where('district_code', '110101')
    ->where('name', 'like', '%Sari%')
    ->page(2)
    ->get();

Testing Connection

php artisan api-co-id:check

Response Format

The API returns:

{
    "is_success": true,
    "message": "Success",
    "data": [...],
    "paging": {
        "page": 1,
        "size": 100,
        "total_item": 34,
        "total_page": 1
    }
}

The get() method extracts and returns the data array. The paginate() method returns a LengthAwarePaginator instance.

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Aslam
• All Contributors

License

The MIT License (MIT). Please see License File for more information.