layout: default title: API Reference nav_order: 5 —

API Reference

Table of contents

1. Models
   1. State
   2. Postcode
   3. Location
2. Services
   1. PostcodeParser
3. Artisan Commands
   1. postcode:download
   2. postcode:seed
4. Example Queries
   1. Full Address Lookup
   2. All Postcodes in a State
   3. Search Locations by Name
   4. Count Statistics

---

Models

State

use Ajangsupardi\PostcodeMy\Models\State;

// Get all states
$states = State::all();

// Find by code
$state = State::where('code', 'KL')->first();

// Get postcodes
$postcodes = $state->postcodes;

Table: states

Column	Type	Description
id	bigint	Primary key
name	string	State name (e.g., “Wilayah Persekutuan Kuala Lumpur”)
code	string	State code (e.g., “KL”)

Relationships:

Method	Type	Related Model
postcodes()	HasMany	Postcode
locations()	HasManyThrough	Location

---

Postcode

use Ajangsupardi\PostcodeMy\Models\Postcode;

// Find by postcode number
$postcode = Postcode::where('postcode', '50000')->first();

// Get with state and locations
$postcode = Postcode::with('state', 'locations')
    ->where('postcode', '50000')
    ->first();

Table: postcodes

Column	Type	Description
id	bigint	Primary key
state_id	bigint	Foreign key to states
postcode	string	Postcode number (e.g., “50000”)
post_office	string	Post office name

Relationships:

Method	Type	Related Model
state()	BelongsTo	State
locations()	HasMany	Location

Scopes:

Scope	Parameters	Description
scopePostcode	$query, $postcode	Filter by postcode number

---

Location

use Ajangsupardi\PostcodeMy\Models\Location;

// Search by name
$locations = Location::name('Jalan')->get();

// Get with postcode hierarchy
$locations = Location::with('postcode.state')
    ->whereHas('postcode', fn ($q) => $q->where('postcode', '50000'))
    ->get();

Table: locations

Column	Type	Description
id	bigint	Primary key
postcode_id	bigint	Foreign key to postcodes
name	string	Location/street name

Relationships:

Method	Type	Related Model
postcode()	BelongsTo	Postcode

Scopes:

Scope	Parameters	Description
scopeName	$query, $name	Search locations by name (LIKE match)

---

Services

PostcodeParser

Parses the bundled CSV file into structured data.

use Ajangsupardi\PostcodeMy\Services\PostcodeParser;

$parser = new PostcodeParser();

// Get all parsed data
$data = $parser->parse();
// Returns: ['states' => [...], 'postcodes' => [...], 'locations' => [...]]

// Get individual sections
$states = $parser->getStates();
$postcodes = $parser->getPostcodes();
$locations = $parser->getLocations();

// Reset parsed cache
$parser->reset();

---

Artisan Commands

postcode:download

Downloads postcode data from Pos Malaysia API.

php artisan postcode:download

This command takes approximately 30 minutes due to API rate limiting.

---

postcode:seed

Seeds all tables from the CSV file.

php artisan postcode:seed

This command is idempotent — safe to run multiple times without creating duplicates.

---

Example Queries

Full Address Lookup

$postcode = Postcode::with('state', 'locations')
    ->where('postcode', '50000')
    ->first();

// Output:
// {
//   "postcode": "50000",
//   "post_office": "Pejabat Pos Kuala Lumpur",
//   "state": {
//     "name": "Wilayah Persekutuan Kuala Lumpur",
//     "code": "KL"
//   },
//   "locations": [
//     { "name": "Jalan Tuanku Abdul Rahman" },
//     { "name": "Jalan Masjid India" }
//   ]
// }

All Postcodes in a State

use Ajangsupardi\PostcodeMy\Models\State;

$state = State::where('code', 'KL')->first();
$postcodes = $state->postcodes()->with('locations')->get();

Search Locations by Name

$locations = Location::where('name', 'LIKE', '%Jalan%')
    ->with('postcode.state')
    ->get();

Count Statistics

use Ajangsupardi\PostcodeMy\Models\{State, Postcode, Location};

$stats = [
    'states'    => State::count(),
    'postcodes' => Postcode::count(),
    'locations' => Location::count(),
];

---