PHPackages                             myparcelcom/timezone-resolver - 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. [Utility & Helpers](/categories/utility)
4. /
5. myparcelcom/timezone-resolver

ActiveLibrary[Utility & Helpers](/categories/utility)

myparcelcom/timezone-resolver
=============================

Resolves a local timezone from address data using the GeoNames API.

02↑2900%[1 PRs](https://github.com/MyParcelCOM/timezone-resolver/pulls)

Since Jun 9Pushed todayCompare

[ Source](https://github.com/MyParcelCOM/timezone-resolver)[ Packagist](https://packagist.org/packages/myparcelcom/timezone-resolver)[ RSS](/packages/myparcelcom-timezone-resolver/feed)WikiDiscussions master Synced today

READMEChangelogDependenciesVersions (1)Used By (0)

timezone-resolver
=================

[](#timezone-resolver)

A lightweight PHP package that resolves an IANA timezone identifier from address data, using the [GeoNames](https://www.geonames.org/) API.

Requirements
------------

[](#requirements)

- PHP 8.4+
- A free [GeoNames account](https://www.geonames.org/login) with the web services enabled

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

[](#installation)

```
composer require myparcelcom/timezone-resolver
```

Usage
-----

[](#usage)

```
use MyParcelCom\TimezoneResolver\GeoNames;

$resolver = new GeoNames(username: 'your-geonames-username');

$timezone = $resolver->getTimezone(
    countryCode: 'NL',
    postalCode: '1043NT',
    city: 'Amsterdam',
);

// 'Europe/Amsterdam'
```

### Method signature

[](#method-signature)

```
public function getTimezone(
    string $countryCode,
    ?string $postalCode = null,
    ?string $city = null,
): ?string
```

- Tries to resolve by `postalCode` first.
- Falls back to `city` if the postal code yields no results.
- Returns `null` if no timezone can be determined.

### Using the interface

[](#using-the-interface)

Depend on `TimezoneResolverInterface` instead of the concrete class to keep your code decoupled:

```
use MyParcelCom\TimezoneResolver\TimezoneResolverInterface;

class MyService
{
    public function __construct(
        private readonly TimezoneResolverInterface $timezoneResolver,
    ) {}
}
```

Configuration
-------------

[](#configuration)

The GeoNames username is passed directly to the constructor. In a Laravel application, bind the interface in a service provider:

```
use MyParcelCom\TimezoneResolver\GeoNames;
use MyParcelCom\TimezoneResolver\TimezoneResolverInterface;

$this->app->bind(
    TimezoneResolverInterface::class,
    fn () => new GeoNames(config('services.geonames.username')),
);
```

```
// config/services.php
'geonames' => [
    'username' => env('GEONAMES_USERNAME'),
],
```

Testing
-------

[](#testing)

```
composer install
vendor/bin/phpunit
```

License
-------

[](#license)

Proprietary — © MyParcel.com

###  Health Score

21

↑

LowBetter than 18% of packages

Maintenance65

Regular maintenance activity

Popularity3

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity11

Early-stage or recently created project

 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.

### Community

Maintainers

![](https://www.gravatar.com/avatar/3841efa190ba5131014f8855131e3d38ef5ccd57c51000966348108e63c83612?d=identicon)[myparcelcom](/maintainers/myparcelcom)

---

Top Contributors

[![daniel-myparcel](https://avatars.githubusercontent.com/u/193501397?v=4)](https://github.com/daniel-myparcel "daniel-myparcel (3 commits)")

### Embed Badge

![Health badge](/badges/myparcelcom-timezone-resolver/health.svg)

```
[![Health](https://phpackages.com/badges/myparcelcom-timezone-resolver/health.svg)](https://phpackages.com/packages/myparcelcom-timezone-resolver)
```

PHPackages © 2026

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