# Addresses

> Parse free-form Pakistani addresses into street, area, city, district, province and postal code, flag a city in the wrong province, and format them.

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

`import { parseAddress, formatAddress } from 'pakdatakit/address'`

Splits a Pakistani mailing address typed as one line into its parts, matching the city, district and province against the library's own lists, and puts parts back together as a single mailing line.

> **Matching against known names**
>
> Only cities, districts and provinces in the library's datasets are recognised. The remaining segments are assigned to street and area.
## Examples

**TypeScript**

```ts
import { parseAddress, formatAddress } from 'pakdatakit';

parseAddress('12 Model Town Lahore');
// → {
//     "raw": "12 Model Town Lahore",
//     "street": "12 Model Town",
//     "area": null,
//     "city": "Lahore",
//     "district": null,
//     "province": "Punjab",
//     "postalCode": null,
//     "warnings": []
//   }

parseAddress('Saddar, Karachi, Punjab');
// → {
//     "raw": "Saddar, Karachi, Punjab",
//     "street": "Saddar",
//     "area": null,
//     "city": "Karachi",
//     "district": null,
//     "province": "Punjab",
//     "postalCode": null,
//     "warnings": [
//       "Karachi is in Sindh, but the address says Punjab"
//     ]
//   }

formatAddress({ street: 'House 12, Street 5', area: 'F-7/2', city: 'Islamabad', postalCode: '44000' });
// → 'House 12, Street 5, F-7/2, Islamabad 44000'
```

**Python**

```python
from pakdatakit import parse_address, format_address

parse_address('12 Model Town Lahore')
# → {
#     "raw": "12 Model Town Lahore",
#     "street": "12 Model Town",
#     "area": None,
#     "city": "Lahore",
#     "district": None,
#     "province": "Punjab",
#     "postal_code": None,
#     "warnings": []
#   }

parse_address('Saddar, Karachi, Punjab')
# → {
#     "raw": "Saddar, Karachi, Punjab",
#     "street": "Saddar",
#     "area": None,
#     "city": "Karachi",
#     "district": None,
#     "province": "Punjab",
#     "postal_code": None,
#     "warnings": [
#       "Karachi is in Sindh, but the address says Punjab"
#     ]
#   }

format_address(street='House 12, Street 5', area='F-7/2', city='Islamabad', postal_code='44000')
# → 'House 12, Street 5, F-7/2, Islamabad 44000'
```

**Dart**

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

parseAddress('12 Model Town Lahore');
// → {
//     "raw": "12 Model Town Lahore",
//     "street": "12 Model Town",
//     "area": null,
//     "city": "Lahore",
//     "district": null,
//     "province": "Punjab",
//     "postalCode": null,
//     "warnings": []
//   }

parseAddress('Saddar, Karachi, Punjab');
// → {
//     "raw": "Saddar, Karachi, Punjab",
//     "street": "Saddar",
//     "area": null,
//     "city": "Karachi",
//     "district": null,
//     "province": "Punjab",
//     "postalCode": null,
//     "warnings": [
//       "Karachi is in Sindh, but the address says Punjab"
//     ]
//   }

formatAddress(street: 'House 12, Street 5', area: 'F-7/2', city: 'Islamabad', postalCode: '44000');
// → 'House 12, Street 5, F-7/2, Islamabad 44000'
```

**C#**

```csharp
using PakDataKit;

Address.Parse("12 Model Town Lahore");
// → {
//     "raw": "12 Model Town Lahore",
//     "street": "12 Model Town",
//     "area": null,
//     "city": "Lahore",
//     "district": null,
//     "province": "Punjab",
//     "postalCode": null,
//     "warnings": []
//   }

Address.Parse("Saddar, Karachi, Punjab");
// → {
//     "raw": "Saddar, Karachi, Punjab",
//     "street": "Saddar",
//     "area": null,
//     "city": "Karachi",
//     "district": null,
//     "province": "Punjab",
//     "postalCode": null,
//     "warnings": [
//       "Karachi is in Sindh, but the address says Punjab"
//     ]
//   }

Address.Format(new ParsedAddress { Street = "House 12, Street 5", Area = "F-7/2", City = "Islamabad", PostalCode = "44000" });
// → "House 12, Street 5, F-7/2, Islamabad 44000"
```

**PHP**

```php
use PakDataKit\Address;

Address::parse('12 Model Town Lahore');
// → {
//     "raw": "12 Model Town Lahore",
//     "street": "12 Model Town",
//     "area": null,
//     "city": "Lahore",
//     "district": null,
//     "province": "Punjab",
//     "postalCode": null,
//     "warnings": []
//   }

Address::parse('Saddar, Karachi, Punjab');
// → {
//     "raw": "Saddar, Karachi, Punjab",
//     "street": "Saddar",
//     "area": null,
//     "city": "Karachi",
//     "district": null,
//     "province": "Punjab",
//     "postalCode": null,
//     "warnings": [
//       "Karachi is in Sindh, but the address says Punjab"
//     ]
//   }

Address::format(['street' => 'House 12, Street 5', 'area' => 'F-7/2', 'city' => 'Islamabad', 'postalCode' => '44000']);
// → 'House 12, Street 5, F-7/2, Islamabad 44000'
```

## Reference

### parseAddress()

```ts
function parseAddress(address: string): ParsedAddress;

interface ParsedAddress {
  raw: string;
  street: string | null;
  area: string | null;
  city: string | null;
  district: string | null;
  province: string | null;
  postalCode: string | null;
  warnings: string[];
}
```

**Parameters.** `address`: the raw address. It works with or without commas between components.

**Returns** the structured components. `warnings` lists inconsistencies found while parsing, such as a city in a different province from the one the address names.

**Caveats.** The postal code is taken from the last standalone 5-digit number that is not a house, plot, box or street number. Known cities, districts and provinces are matched from the datasets, and the remaining segments are assigned to `street` and `area`.

**Related:** [`formatAddress()`](#formataddress), [`getProvince()`](https://pakdatakit.dev/docs/geo/), [postal codes](https://pakdatakit.dev/docs/postal/).

### formatAddress()

```ts
function formatAddress(
  parts: Partial<ParsedAddress> & { raw?: string },
): string;
```

**Parameters.** `parts`: any of the components of a `ParsedAddress`; a parsed address can be passed back in as it is.

**Returns** a single mailing line: street, area, city (or the district when there is no city) and province, separated by commas, then the postal code. When no component is given it returns `raw`, or `""`.

**Caveats.** Only the components provided are included; no postal code is invented.

**Related:** [`parseAddress()`](#parseaddress).

## Related

- [TypeScript API reference for `pakdatakit/address`](https://pakdatakit.dev/api/typescript/address/)
- [Geography](https://pakdatakit.dev/docs/geo/) and [postal codes](https://pakdatakit.dev/docs/postal/)
- [Data sources](https://pakdatakit.dev/data/)
