# Courier (experimental)

> Experimental. Map a Pakistani courier's own delivery status to one shared vocabulary, and normalise how a city is written for courier forms.

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

`import { mapCourierStatus, normalizeCityForCourier } from 'pakdatakit/courier'`

> **Experimental**
>
> Only PostEx and one Leopards status are mapped so far. The mapping and the `CourierStatus` values may change in a minor release as other couriers' lists are added.
Maps a courier's own status (its name, numeric ID or code, as the courier documents it) to one vocabulary, from order to delivery or return. It also maps the way a customer or a courier writes a city to the city's name in pakdatakit's city list, so orders can be matched against a courier's service list. No API is called.

## Examples

**TypeScript**

```ts
import { mapCourierStatus, normalizeCityForCourier } from 'pakdatakit';

mapCourierStatus('PostEx', 'Out for Delivery');
// → 'out-for-delivery'

mapCourierStatus('TCS', 'Delivered');
// → null

normalizeCityForCourier('LHR');
// → 'Lahore'

normalizeCityForCourier('lyallpur');
// → 'Faisalabad'
```

**Python**

```python
from pakdatakit import map_courier_status, normalize_city_for_courier

map_courier_status('PostEx', 'Out for Delivery')
# → 'out-for-delivery'

map_courier_status('TCS', 'Delivered')
# → None

normalize_city_for_courier('LHR')
# → 'Lahore'

normalize_city_for_courier('lyallpur')
# → 'Faisalabad'
```

**Dart**

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

mapCourierStatus('PostEx', 'Out for Delivery');
// → CourierStatus.outForDelivery

mapCourierStatus('TCS', 'Delivered');
// → null

normalizeCityForCourier('LHR');
// → 'Lahore'

normalizeCityForCourier('lyallpur');
// → 'Faisalabad'
```

**C#**

```csharp
using PakDataKit;

Courier.MapStatus("PostEx", "Out for Delivery");
// → CourierStatus.OutForDelivery

Courier.MapStatus("TCS", "Delivered");
// → null

Courier.NormalizeCity("LHR");
// → "Lahore"

Courier.NormalizeCity("lyallpur");
// → "Faisalabad"
```

**PHP**

```php
use PakDataKit\Courier;

Courier::mapStatus('PostEx', 'Out for Delivery');
// → 'out-for-delivery'

Courier::mapStatus('TCS', 'Delivered');
// → null

Courier::normalizeCity('LHR');
// → 'Lahore'

Courier::normalizeCity('lyallpur');
// → 'Faisalabad'
```

## Reference

### mapCourierStatus()

```ts
function mapCourierStatus(
  courier: string,
  raw: string | number,
): CourierStatus | null;

type CourierStatus =
  | 'pending'
  | 'booked'
  | 'picked-up'
  | 'in-transit'
  | 'out-for-delivery'
  | 'attempted'
  | 'under-review'
  | 'delivered'
  | 'returning'
  | 'returned'
  | 'cancelled';
```

**Parameters.** `courier`: `TCS`, `Leopards`, `PostEx`, `M&P`, `Trax` or `BlueEx` (case-insensitive; `LCS`, `MnP` and `Blue Ex` are accepted). `raw`: the status as the courier returned it.

**Returns** the status, or `null`. It never throws. Matching ignores case and extra spaces. PostEx's `Attempt Made: <reason>` history messages map to `attempted`.

**Caveats.** Only statuses the courier documents publicly are mapped: PostEx's API guide and one Leopards status ("Returned to Shipper"). TCS, M&P, Trax and BlueEx publish no list, so they always return `null`, as does any status not in the list. Experimental: the mapping and the `CourierStatus` values may change in a minor release.

**Related:** [`normalizeCityForCourier()`](#normalizecityforcourier).

### normalizeCityForCourier()

```ts
function normalizeCityForCourier(input: string): string | null;
```

**Parameters.** `input`: a city as written. Accepts the exact name in any case, short forms (`LHR`, `Khi`, `Pindi`, `Isb`, `FSD`), the old name Lyallpur, a trailing "city", and the main cities in Urdu script.

**Returns** a city from the city list, or `null`. It never throws.

**Caveats.** The short forms are common usage, not an official list.

**Related:** [Geography](https://pakdatakit.dev/docs/geo/), [address](https://pakdatakit.dev/docs/address/).

## Related

- [Address](https://pakdatakit.dev/docs/address/) and [data quality](https://pakdatakit.dev/docs/quality/) checks for order forms.
- [API reference for `pakdatakit/courier`](https://pakdatakit.dev/api/typescript/courier/).
