PHPackages                             nomisoft/royal-mail-tracking-api - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. nomisoft/royal-mail-tracking-api

AbandonedArchivedLibrary[API Development](/categories/api)

nomisoft/royal-mail-tracking-api
================================

A library to ease development when working with the Royal Mail Tracking API

1.0.2(9y ago)185MITPHPPHP >=5.3.0

Since Jun 7Pushed 9y ago1 watchersCompare

[ Source](https://github.com/nomisoft/royal-mail-tracking-api)[ Packagist](https://packagist.org/packages/nomisoft/royal-mail-tracking-api)[ Docs](https://github.com/nomisoft/royal-mail-tracking-api)[ RSS](/packages/nomisoft-royal-mail-tracking-api/feed)WikiDiscussions master Synced 4w ago

READMEChangelog (3)DependenciesVersions (4)Used By (0)

Royal Mail Tracking API
=======================

[](#royal-mail-tracking-api)

To be able to track items through the Royal Mail API you'll need to be a Royal Mail account holder and have approved access to the Tracking API through the Royal Mail developer portal at

Installation
------------

[](#installation)

```
composer require nomisoft/royal-mail-tracking-api

```

Usage
-----

[](#usage)

You'll need the tracking reference number of the item you wish to retrieve details of as well as your Client ID, Client Secret and App ID (all available from the Royal Mail developer portal)

### Single item summary

[](#single-item-summary)

```
use \Nomisoft\RoyalMailTrackingApi\RoyalMail;
use \Nomisoft\RoyalMailTrackingApi\RoyalMailException;

$rm = RoyalMail::init('CLIENT_ID', 'CLIENT_SECRET', 'APP_ID');
try {
    $response = $rm->getSingleItemSummary('XX12345678XX');
}catch (SoapFault $e) {
	echo $e->getMessage();
} catch(RoyalMailException $e) {
	echo $e->getMessage() . ' - ' . $e->getCause();
}
```

The response returned is an array containing a DateTime object, the status and summary text

```
Array
(
    [datetime] => DateTime Object
        (
            [date] => 2016-06-01 12:30:00
            [timezone_type] => 3
            [timezone] => Europe/London
        )
    [status] => Delivered
    [summary] => Item XX12345678XX was collected and signed for by the addressee on the 2016-06-01 from Kidderminster DO.
)
```

### Single item full history

[](#single-item-full-history)

```
use \Nomisoft\RoyalMailTrackingApi\RoyalMail;
$rm = RoyalMail::init('CLIENT_ID', 'CLIENT_SECRET', 'APP_ID');
$response = $rm->getSingleItemHistory('XX12345678XX');
```

The response returned is a multidimensional array. Each delivery status update contains a DateTime object, the location and the status

```
Array
(
    [0] => Array
        (
            [datetime] => DateTime Object
                (
                    [date] => 2016-06-01 12:30:00
                    [timezone_type] => 3
                    [timezone] => Europe/London
                )
            [location] => Kidderminster DO
            [status] => Delivered
        )

    [1] => Array
        (
            [datetime] => DateTime Object
                (
                    [date] => 2016-05-31 15:30:00
                    [timezone_type] => 3
                    [timezone] => Europe/London
                )
            [location] => Kidderminster DO
            [status] => We have your item
        )

    [2] => Array
        (
            [datetime] => DateTime Object
                (
                    [date] => 2016-05-31 12:30:00
                    [timezone_type] => 3
                    [timezone] => Europe/London
                )
            [location] => Kidderminster DO
            [status] => Delivery attempted
        )

    [3] => Array
        (
            [datetime] => DateTime Object
                (
                    [date] => 2016-05-28 10:00:00
                    [timezone_type] => 3
                    [timezone] => Europe/London
                )
            [location] => Medway Mail Centre
            [status] => It's on its way.
        )

)
```

### Multiple item summaries

[](#multiple-item-summaries)

```
use \Nomisoft\RoyalMailTrackingApi\RoyalMail;
$rm = RoyalMail::init('CLIENT_ID', 'CLIENT_SECRET', 'APP_ID');
$response = $rm->getMultiItemSummary(array('XX12345678XX','ZZ12345678ZZ'));
```

The response returned is a multidimensional array with the tracking reference number as the key. Each item contains a DateTime object, status and the summary

```
Array
(
    [XX12345678XX] => Array
        (
            [datetime] => DateTime Object
                (
                    [date] => 2016-06-01 12:30:00
                    [timezone_type] => 3
                    [timezone] => Europe/London
                )
            [status] => Delivered
            [summary] => Item XX12345678XX was collected and signed for by the addressee on the 2016-06-01 from Kidderminster DO.
        )

    [ZZ12345678ZZ] => Array
        (
            [datetime] => DateTime Object
                (
                    [date] => 2016-06-01 12:30:00
                    [timezone_type] => 3
                    [timezone] => Europe/London
                )
            [status] => Delivered
            [summary] => We have a record of item ZZ12345678ZZ as being delivered from Fort William DO on 2016-06-01.
        )
)
```

### Proof of delivery

[](#proof-of-delivery)

```
use \Nomisoft\RoyalMailTrackingApi\RoyalMail;
$rm = RoyalMail::init('CLIENT_ID', 'CLIENT_SECRET', 'APP_ID');
$response = $rm->getProofOfDelivery('XX12345678XX');
```

The response returned is an array containing a DateTime object and the name of the person that signed for the parcel

```
Array
(
    [datetime] => DateTime Object
        (
            [date] => 2016-06-01 12:30:00
            [timezone_type] => 3
            [timezone] => Europe/London
        )
    [name] => Smith
)
```

### Errors

[](#errors)

A RoyalMailException Exception is thrown if an error response is received from the API. Calling the getMessage() function will return Royal Mail's error description. There's also an additional getCause() function which will return the value of the 'Cause' field returned by the API

```
try {
    $response = $rm->getSingleItemSummary('XX12345678XX');
} catch(RoyalMailException $e) {
	echo $e->getMessage();
	echo $e->getCause();
}
```

If the item was delivered over 30 days ago you might see the following printed from the above sample code

```
Tracking data are not available for barcode reference XX12345678XX
It is not possible to provide information about events that occurred more than 30 days ago

```

###  Health Score

27

—

LowBetter than 47% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity11

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity60

Established project with proven stability

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~25 days

Total

3

Last Release

3625d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/6333315?v=4)[Simon](/maintainers/nomisoft)[@nomisoft](https://github.com/nomisoft)

---

Top Contributors

[![nomisoft](https://avatars.githubusercontent.com/u/6333315?v=4)](https://github.com/nomisoft "nomisoft (5 commits)")

### Embed Badge

![Health badge](/badges/nomisoft-royal-mail-tracking-api/health.svg)

```
[![Health](https://phpackages.com/badges/nomisoft-royal-mail-tracking-api/health.svg)](https://phpackages.com/packages/nomisoft-royal-mail-tracking-api)
```

###  Alternatives

[exsyst/swagger

A php library to manipulate Swagger specifications

35816.3M7](/packages/exsyst-swagger)[hubspot/api-client

Hubspot API client

24015.5M18](/packages/hubspot-api-client)[pocketmine/bedrock-protocol

An implementation of the Minecraft: Bedrock Edition protocol in PHP

172437.8k11](/packages/pocketmine-bedrock-protocol)[botman/driver-telegram

Telegram driver for BotMan

94452.6k6](/packages/botman-driver-telegram)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)