PHPackages                             data-values/geo - 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. data-values/geo

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

data-values/geo
===============

Geographical value objects, parsers and formatters

4.6.0(8mo ago)17646.1k↓21%10[2 issues](https://github.com/DataValues/Geo/issues)[1 PRs](https://github.com/DataValues/Geo/pulls)17GPL-2.0-or-laterPHPPHP >=8.1CI passing

Since Nov 17Pushed 5mo ago12 watchersCompare

[ Source](https://github.com/DataValues/Geo)[ Packagist](https://packagist.org/packages/data-values/geo)[ Docs](https://github.com/DataValues/Geo)[ GitHub Sponsors](https://github.com/JeroenDeDauw)[ RSS](/packages/data-values-geo/feed)WikiDiscussions master Synced 1w ago

READMEChangelog (10)Dependencies (9)Versions (42)Used By (17)

DataValues Geo
==============

[](#datavalues-geo)

Small library for **parsing, formatting, and representing coordinates**. This library supports multiple coordinate formats, is well-tested, and is used by the software behind Wikipedia and Wikidata.

[![GitHub Workflow Status](https://camo.githubusercontent.com/62b6f88190719ef5cdda912ac241a028cf437c709661d062dcf39128a75e7d30/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f4461746156616c7565732f47656f2f7068702e796d6c3f6272616e63683d6d6173746572)](https://github.com/DataValues/Geo/actions?query=workflow%3Aphp)

On [Packagist](https://packagist.org/packages/data-values/geo): [![Latest Stable Version](https://camo.githubusercontent.com/3008b062f3a0ad15a5e8c8ae0bd1e28ec14aa90821fcae9e12278d3ade3aed72/68747470733a2f2f706f7365722e707567782e6f72672f646174612d76616c7565732f67656f2f762f737461626c65)](https://packagist.org/packages/data-values/geo)[![Download count](https://camo.githubusercontent.com/9b357c24d46e6fc4190fc0e56032883058b9560bb189fda46b917c8dc9c8a2bd/68747470733a2f2f706f7365722e707567782e6f72672f646174612d76616c7565732f67656f2f646f776e6c6f616473)](https://packagist.org/packages/data-values/geo)

Usage
-----

[](#usage)

To **parse a string to a `LatLongValue` object** you use one of the coordinate parsers.

```
$parser = new LatLongParser();
$latLongValue = $parser->parse('55.7557860 N, 37.6176330 W');
var_dump($latLongValue->getLongitude()); // float: -37.6176330
```

These parsers are provided:

- `LatLongParser` - Facade for format-specific parsers. In most cases, you will be using this one
- `DdCoordinateParser` - Parses decimal degree coordinates
- `DmCoordinateParser` - Parses decimal minute coordinates
- `DmsCoordinateParser` - Parses degree minute second coordinates
- `FloatCoordinateParser` - Parses float coordinates
- `GlobeCoordinateParser` - Parses coordinates into `GlobeCoordinateValue` objects

To **turn a coordinate object into a string** you use one of the coordinate formatters.

```
$formatter = new LatLongFormatter();
$coordinateString = $formatter->format(new LatLongValue(42.23, 13.37));
```

These formatters are provided:

- `LatLongFormatter` - Formats a `LatLongValue` into any of the supported formats
- `GlobeCoordinateFormatter` - Formats a `GlobeCoordinateValue`

To **represent a set of coordinates** you use one of the Value Objects.

`LatLongValue` has a float latitude and longitude. `GlobeCoordinateValue` wraps `LatLongValue`and adds a precision and a globe identifier.

The **supported coordinate formats** are:

- Degree minute second (`55° 45' 20.8296", -37° 37' 3.4788"` or `55° 45' 20.8296" N, 37° 37' 3.4788" W`)
- Decimal minute (`55° 30', -37° 30'` or `55° 30' N, 37° 30' W`)
- Decimal degree (`55.7557860°, -37.6176330°` or `55.7557860° N, 37.6176330° W`)
- Float (`55.7557860, -37.6176330` or `55.7557860 N, 37.6176330 W`)

The parsers and formatters allow you to customize the used symbols for degrees, minutes, and seconds and to change the letters used to indicate the direction (N, E, S, W).

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

[](#requirements)

**Geo 4.x:** PHP 7.1 or later (tested with PHP 7.1 up to PHP 8.4)

**Geo 3.x:** PHP 5.5 or later (tested with PHP 5.5 up to PHP 7.4 and HHVM)

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

[](#installation)

To add this package as a local, per-project dependency to your project, simply add a dependency on `data-values/geo` to your project's `composer.json` file. Here is a minimal example of a `composer.json` file that just defines a dependency on version 4.x of this package:

```
    {
        "require": {
            "data-values/geo": "^4.0.0"
        }
    }
```

Running the tests
-----------------

[](#running-the-tests)

For tests only

```
composer test

```

For style checks only

```
composer cs

```

For a full CI run

```
composer ci

```

Authors
-------

[](#authors)

DataValues Geo is based upon and contains a lot of code written by [Jeroen De Dauw](https://github.com/JeroenDeDauw) for the [Maps](https://github.com/JeroenDeDauw/Maps) and [Semantic MediaWiki](https://semantic-mediawiki.org/) projects.

Significant contributions were made by the Wikidata team, as [Wikimedia Germany](https://wikimedia.de/en)employees for the [Wikidata project](https://wikidata.org/).

Release notes
-------------

[](#release-notes)

### 4.6.0 (2025-09-23)

[](#460-2025-09-23)

- Updated requirement for `data-values/interfaces` to `^1.1.0`
- Dropped support for PHP 7.4 and 8.0
- Testing on PHP 8.4

### 4.5.1 (2025-01-06)

[](#451-2025-01-06)

- Restored support for PHP 7.4

### 4.5.0 (2024-12-10)

[](#450-2024-12-10)

- Dropped support for PHP 7.3 and 7.4
- Improved support for PHP 8.4 by explicitly declaring nullable types
- Upgraded `mediawiki/mediawiki-codesniffer` rules to version 45.0.0
- Added testing with PHP 8.2 and 8.3

### 4.4.0 (2022-10-21)

[](#440-2022-10-21)

- Implemented `__serialize` and `__unserialize` in `LatLongValue` and `GlobeCoordinateValue`, improving compatibility with PHP 8.1
- Added `LatLongValue::getSerializationForHash`; classes that use the PHP serialization of a `LatLongValue` for a hash should instead call this method

### 4.3.0 (2021-04-21)

[](#430-2021-04-21)

- Raised the minimum PHP version from 7.1 to 7.3

### 4.2.3 (2021-04-23)

[](#423-2021-04-23)

- `GlobeCoordinateValue::newFromArray` now supports numeric strings (thanks @Silvan-WMDE)

### 4.2.2 (2021-01-20)

[](#422-2021-01-20)

- Added compatibility with `data-values/data-values` 3.x
- Added compatibility with `data-values/interfaces` 1.x

### 4.2.1 (2019-12-18)

[](#421-2019-12-18)

- Fixed `GlobeCoordinateParser` not being able to parse multiple values (4.2.0 regression)

### 4.2.0 (2019-09-20)

[](#420-2019-09-20)

- Added `GlobeCoordinateValue::withPrecision`

### 4.1.0 (2018-10-29)

[](#410-2018-10-29)

- Added "PHP strict types" to all files
- `LatLongValue` no longer extends `DataValueObject`
- `GlobeCoordinateValue` no longer extends `DataValueObject`
- Reordered methods in `LatLongValue` and `GlobeCoordinateValue` for readability
- Undeprecated `LatLongValue::newFromArray`
- Undeprecated `GlobeCoordinateValue::newFromArray`

### 4.0.1 (2018-08-10)

[](#401-2018-08-10)

- Fixed parsing of coordinates with lowercase S/W directions
- Fixed parsing DMS coordinates that omit a single minute number

### 3.0.1 (2018-08-01)

[](#301-2018-08-01)

- Fixed parsing of coordinates with lowercase S/W directions

### 2.1.2 (2018-08-01)

[](#212-2018-08-01)

- Fixed parsing of coordinates with lowercase S/W directions

### 4.0.0 (2018-07-13)

[](#400-2018-07-13)

- Updated the minimum required PHP version from 5.5.9 to 7.1
- Added scalar type hints
- Added return type hints
- Added nullable type hints
- Made constant visibility explicit
- Constructing an invalid `LatLongValue` now causes `InvalidArgumentException` instead of `OutOfRangeException`

### 3.0.0 (2018-03-20)

[](#300-2018-03-20)

- Removed `DATAVALUES_GEO_VERSION` constant
- The parsers no longer extend `StringValueParser`
    - They no longer have public methods `setOptions` and `getOptions`
    - They no longer have protected field `options`
    - They no longer have protected methods `requireOption`, `defaultOption` and `stringParse`
    - `GlobeCoordinateParser` and `LatLongParser` no longer have protected method `getOption`
- Made several protected fields and methods private
    - All fields of `LatLongValue`
    - The `detect…Precision` methods in `GlobeCoordinateParser`
    - `LatLongParser::getParsers`
- Removed public static method `LatLongParser::areCoordinates`
- Dropped dependence on the DataValues Common library
- Removed long deprecated class aliases
    - `DataValues\GlobeCoordinateValue` (now in `DataValues\Geo\Values`)
    - `DataValues\LatLongValue` (now in `DataValues\Geo\Values`)
    - `DataValues\Geo\Formatters\GeoCoordinateFormatter` (now `LatLongFormatter`)
    - `DataValues\Geo\Parsers\GeoCoordinateParser` (now `LatLongParser`)

### 2.1.1 (2017-08-09)

[](#211-2017-08-09)

- Allow use with ~0.4.0 of DataValues/Common

### 2.1.0 (2017-08-09)

[](#210-2017-08-09)

- Remove MediaWiki integration
- Make use of the …`::class` feature
- Add .gitattributes to exclude unnecessary files from git exports
- Use Wikibase CodeSniffer instead of MediaWiki's
- Move to short array syntax

### 2.0.1 (2017-06-26)

[](#201-2017-06-26)

- Fixed `GlobeCoordinateValue::newFromArray` and `LatLongValue::newFromArray` not accepting mixed values.
- Deprecated `GlobeCoordinateValue::newFromArray` and `LatLongValue::newFromArray`.
- Updated the minimum required PHP version from 5.3 to 5.5.9.

### 2.0.0 (2017-05-09)

[](#200-2017-05-09)

- `GlobeCoordinateValue` no longer accepts empty strings as globes.
- `GlobeCoordinateValue` no longer accept precisions outside the \[-360..+360\] interval.
- Changed hash calculation of `GlobeCoordinateValue` in an incompatible way.
- Renamed `GeoCoordinateFormatter` to `LatLongFormatter`, leaving a deprecated alias.
- Renamed `GeoCoordinateParser` to `LatLongParser`, leaving a deprecated alias.
- Renamed `GeoCoordinateParserBase` to `LatLongParserBase`.
- Deprecated `LatLongParser::areCoordinates`.

### 1.2.2 (2017-03-14)

[](#122-2017-03-14)

- Fixed multiple rounding issues in `GeoCoordinateFormatter`.

### 1.2.1 (2016-12-16)

[](#121-2016-12-16)

- Fixed another IEEE issue in `GeoCoordinateFormatter`.

### 1.2.0 (2016-11-11)

[](#120-2016-11-11)

- Added missing inline documentation to public methods and constants.
- Added a basic PHPCS rule set, can be run with `composer phpcs`.

### 1.1.8 (2016-10-12)

[](#118-2016-10-12)

- Fixed an IEEE issue in `GeoCoordinateFormatter`
- Fixed a PHP 7.1 compatibility issue in a test

### 1.1.7 (2016-05-25)

[](#117-2016-05-25)

- Made minor documentation improvements

### 1.1.6 (2016-04-02)

[](#116-2016-04-02)

- Added compatibility with DataValues Common 0.3.x

### 1.1.5 (2015-12-28)

[](#115-2015-12-28)

- The component can now be installed together with DataValues Interfaces 0.2.x

### 1.1.4 (2014-11-25)

[](#114-2014-11-25)

- Add a fallback to default on invalid precision to more places.

### 1.1.3 (2014-11-19)

[](#113-2014-11-19)

- Fall back to default on invalid precision instead of dividing by zero.

### 1.1.2 (2014-11-18)

[](#112-2014-11-18)

- Precision detection in `GlobeCoordinateParser` now has a lower bound of 0.00000001°

### 1.1.1 (2014-10-21)

[](#111-2014-10-21)

- Removed remaining uses of class aliases from messages and comments
- Fixed some types in documentation

### 1.1.0 (2014-10-09)

[](#110-2014-10-09)

- Made the component installable with DataValues 1.x
- `GeoCoordinateFormatter` now supports precision in degrees
- `GlobeCoordinateFormatter` now passes the globe precision to the `GeoCoordinateFormatter` it uses
- Introduced `FORMAT_NAME` class constants on ValueParsers to use them as expectedFormat
- Changed ValueParsers to pass rawValue and expectedFormat arguments when constructing a `ParseException`

### 1.0.0 (2014-07-31)

[](#100-2014-07-31)

- All classes and interfaces have been moved into the `DataValues\Geo` namespace
    - `DataValues\LatLongValue` has been left as deprecated alias
    - `DataValues\GlobeCoordinateValue` has been left as deprecated alias
- Globe in `GlobeCoordinateValue` now defaults to `http://www.wikidata.org/entity/Q2`

### 0.2.0 (2014-07-07)

[](#020-2014-07-07)

- Removed deprecated `GeoCoordinateValue`
- Added `GlobeMath`

### 0.1.2 (2014-01-22)

[](#012-2014-01-22)

- Added support for different levels of spacing in GeoCoordinateFormatter

### 0.1.1 (2013-11-30)

[](#011-2013-11-30)

- Added support for direction notation to GeoCoordinateFormatter
- Decreased complexity of GeoCoordinateFormatter
- Decreased complexity and coupling of GeoCoordinateFormatterTest

### 0.1.0 (2013-11-17)

[](#010-2013-11-17)

Initial release with these features:

- LatLongValue
- GlobeCoordinateValue
- GeoCoordinateFormatter
- GlobeCoordinateFormatter
- DdCoordinateParser
- DmCoordinateParser
- DmsCoordinateParser
- FloatCoordinateParser
- GeoCoordinateParser
- GlobeCoordinateParser

Links
-----

[](#links)

- [DataValues Geo on Packagist](https://packagist.org/packages/data-values/geo)
- [DataValues on Wikimedia's Phabricator](https://phabricator.wikimedia.org/project/view/122/)

###  Health Score

61

—

FairBetter than 99% of packages

Maintenance64

Regular maintenance activity

Popularity47

Moderate usage in the ecosystem

Community39

Small or concentrated contributor base

Maturity84

Battle-tested with a long release history

 Bus Factor1

Top contributor holds 59.5% 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 ~114 days

Recently: every ~403 days

Total

39

Last Release

259d ago

Major Versions

1.2.2 → 2.0.02017-05-09

2.1.1 → 3.0.02018-03-20

3.0.0 → 4.0.02018-07-13

2.1.x-dev → 4.0.12018-08-10

3.0.x-dev → 4.2.12019-12-19

PHP version history (7 changes)0.1PHP >=5.3.0

2.0.1PHP >=5.5.9

4.0.0PHP >=7.1

4.3.0PHP >=7.3

4.5.0PHP >=8.0

4.5.1PHP >=7.4

4.6.0PHP >=8.1

### Community

Maintainers

![](https://www.gravatar.com/avatar/451bd4039d530fed8f9c3da91bfa519233a397d2182cdfdcad700f6cfea19b7f?d=identicon)[Jeroen De Dauw](/maintainers/Jeroen%20De%20Dauw)

![](https://avatars.githubusercontent.com/u/22235?v=4)[Stefan Wasilewski](/maintainers/SMW)[@smw](https://github.com/smw)

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

---

Top Contributors

[![JeroenDeDauw](https://avatars.githubusercontent.com/u/146040?v=4)](https://github.com/JeroenDeDauw "JeroenDeDauw (323 commits)")[![thiemowmde](https://avatars.githubusercontent.com/u/6576639?v=4)](https://github.com/thiemowmde "thiemowmde (98 commits)")[![mariushoch](https://avatars.githubusercontent.com/u/2446964?v=4)](https://github.com/mariushoch "mariushoch (20 commits)")[![JanZerebecki](https://avatars.githubusercontent.com/u/7452727?v=4)](https://github.com/JanZerebecki "JanZerebecki (18 commits)")[![addshore](https://avatars.githubusercontent.com/u/3308769?v=4)](https://github.com/addshore "addshore (14 commits)")[![manicki](https://avatars.githubusercontent.com/u/3524114?v=4)](https://github.com/manicki "manicki (10 commits)")[![reedy](https://avatars.githubusercontent.com/u/67615?v=4)](https://github.com/reedy "reedy (9 commits)")[![lucaswerkmeister](https://avatars.githubusercontent.com/u/2346599?v=4)](https://github.com/lucaswerkmeister "lucaswerkmeister (8 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (6 commits)")[![Ladsgroup](https://avatars.githubusercontent.com/u/5351225?v=4)](https://github.com/Ladsgroup "Ladsgroup (6 commits)")[![codders](https://avatars.githubusercontent.com/u/17782?v=4)](https://github.com/codders "codders (4 commits)")[![filbertkm](https://avatars.githubusercontent.com/u/135401?v=4)](https://github.com/filbertkm "filbertkm (4 commits)")[![tobijat](https://avatars.githubusercontent.com/u/2997252?v=4)](https://github.com/tobijat "tobijat (3 commits)")[![adrianheine](https://avatars.githubusercontent.com/u/139208?v=4)](https://github.com/adrianheine "adrianheine (3 commits)")[![bekh6ex](https://avatars.githubusercontent.com/u/4264331?v=4)](https://github.com/bekh6ex "bekh6ex (3 commits)")[![JonasKress](https://avatars.githubusercontent.com/u/13198391?v=4)](https://github.com/JonasKress "JonasKress (3 commits)")[![rosalieper](https://avatars.githubusercontent.com/u/15235452?v=4)](https://github.com/rosalieper "rosalieper (3 commits)")[![legoktm](https://avatars.githubusercontent.com/u/81392?v=4)](https://github.com/legoktm "legoktm (2 commits)")[![gmelikov](https://avatars.githubusercontent.com/u/3868786?v=4)](https://github.com/gmelikov "gmelikov (1 commits)")[![reiz](https://avatars.githubusercontent.com/u/652130?v=4)](https://github.com/reiz "reiz (1 commits)")

---

Tags

dmsgeogeographicallatitudelongitudecoordinatescoordinatelatlongsecondsMinuteswikidatadatavaluesformattersparsersDegrees

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan, Psalm

Type Coverage Yes

### Embed Badge

![Health badge](/badges/data-values-geo/health.svg)

```
[![Health](https://phpackages.com/badges/data-values-geo/health.svg)](https://phpackages.com/packages/data-values-geo)
```

###  Alternatives

[mjaschen/phpgeo

Simple Yet Powerful Geo Library

1.6k9.1M26](/packages/mjaschen-phpgeo)[php-coord/php-coord

PHPCoord is a PHP library to aid in handling coordinates. It can convert coordinates for a point from one system to another and also calculate distance between points.

109966.2k12](/packages/php-coord-php-coord)[anthonymartin/geo-location

Powerful GeoCoding library: Retrieve bounding box coordinates, distances between geopoints, point in polygon, get longitude and latitude from addresses and more with GeoLocation for PHP

196987.0k10](/packages/anthonymartin-geo-location)[data-values/common

Contains common implementations of the interfaces defined by DataValuesInterfaces

11979.7k14](/packages/data-values-common)[data-values/number

Numerical value objects, parsers and formatters

18309.1k14](/packages/data-values-number)[laravie/geotools

Geo-related tools PHP 7+ library

18122.1k1](/packages/laravie-geotools)

PHPackages © 2026

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