README

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

Includes support for Holiday API (Indonesian public holidays) and Shipping Cost API (expedition/shipping rates).

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
API_CO_ID_HOLIDAY_BASE_URL=https://use.api.co.id/holidays/indonesia
API_CO_ID_EXPEDITION_BASE_URL=https://use.api.co.id/expedition

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();

More endpoints coming soon.

Holiday API

use Aslam\ApiCoId\Facades\Holiday;

// Get all holidays for a year
Holiday::holidays(year: 2025)->get();

// Check if a date is a holiday (returns array)
Holiday::check('2025-01-01');

// Get upcoming holidays (default limit)
Holiday::upcoming()->get();

// Get upcoming holidays with custom limit
Holiday::upcoming()->limit(5)->get();

Shipping Cost API

use Aslam\ApiCoId\Facades\Shipping;

// Calculate shipping cost
Shipping::cost(origin: '3204282001', destination: '3204402005', weight: 1)->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.

Endpoint	Cost	Type
Provinces, Regencies, Districts, Villages	0 points	🆓 Free
Holidays	0 points	🆓 Free
Shipping Cost	0 points	🆓 Free
Search, Postal Codes	2 points	💰 Paid
KTP OCR, SIM OCR	150–300 points	💰 Paid

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

License

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

aslammaududy / laravel-api-co-id

Maintainers

Package info

Fund package maintenance!

Statistics

Security