# Postal codes and post offices

> Postal codes of Pakistani cities and every delivery post office in Pakistan Post's directory, including villages.

Source: https://pakdatakit.dev/docs/postal/

`import { getPostalCode, getCityByPostalCode, getPostOffice, searchPostOffices } from 'pakdatakit/postal'`

Two datasets: the main postal codes of the cities the package lists, and Pakistan Post's full directory of about 2,560 delivery post offices, including towns and villages.

## Examples

**TypeScript**

```ts
import { getPostalCode, getCityByPostalCode, getPostOffice } from 'pakdatakit';

getPostalCode('Lahore');
// → '54000'

getCityByPostalCode('54000');
// → 'Lahore'

getPostOffice('12380');
// → {
//     "code": "12380",
//     "office": "Chak Dhamni",
//     "town": "Chak Dhamni",
//     "district": null,
//     "province": "Azad Jammu and Kashmir"
//   }
```

**Python**

```python
from pakdatakit import get_postal_code, get_city_by_postal_code, get_post_office

get_postal_code('Lahore')
# → '54000'

get_city_by_postal_code('54000')
# → 'Lahore'

get_post_office('12380')
# → {
#     "code": "12380",
#     "office": "Chak Dhamni",
#     "town": "Chak Dhamni",
#     "district": None,
#     "province": "Azad Jammu and Kashmir"
#   }
```

**Dart**

```dart
import 'package:pakdatakit/pakdatakit.dart';

getPostalCode('Lahore');
// → '54000'

getCityByPostalCode('54000');
// → 'Lahore'

getPostOffice('12380');
// → {
//     "code": "12380",
//     "office": "Chak Dhamni",
//     "town": "Chak Dhamni",
//     "district": null,
//     "province": "Azad Jammu and Kashmir"
//   }
```

**C#**

```csharp
using PakDataKit;

Postal.GetCode("Lahore");
// → "54000"

Postal.GetCity("54000");
// → "Lahore"

Postal.GetPostOffice("12380");
// → {
//     "code": "12380",
//     "office": "Chak Dhamni",
//     "town": "Chak Dhamni",
//     "district": null,
//     "province": "Azad Jammu and Kashmir"
//   }
```

**PHP**

```php
use PakDataKit\Postal;

Postal::getCode('Lahore');
// → '54000'

Postal::getCity('54000');
// → 'Lahore'

Postal::getPostOffice('12380');
// → {
//     "code": "12380",
//     "office": "Chak Dhamni",
//     "town": "Chak Dhamni",
//     "district": null,
//     "province": "Azad Jammu and Kashmir"
//   }
```

## Reference

### getPostalCode()

```ts
function getPostalCode(city: string): string | null;
```

**Returns** the primary postal code of a city (case-insensitive), or `null` for an unknown city.

### getCityByPostalCode()

```ts
function getCityByPostalCode(postalCode: string): string | null;
```

**Returns** the city for one of its own post offices. A village code returns `null`; use `getPostOffice()` for those.

### getPostOffice()

```ts
function getPostOffice(code: string): PostOffice | null;

interface PostOffice {
  code: string;
  office: string;
  town: string;
  district: string | null;
  province: string;
}
```

**Returns** any delivery post office by its five-digit code.

**Caveats.** The directory is a separate data file, loaded only when these functions are first called.

**Related:** [`searchPostOffices()`](https://pakdatakit.dev/api/typescript/postal/functions/searchpostoffices/), [`scoreAddress()`](https://pakdatakit.dev/api/typescript/quality/functions/scoreaddress/), [data sources](https://pakdatakit.dev/data/).
