---
title: Geo Parser 4.x
description: Installation, usage, return values and exceptions for LongitudeOne Geo Parser 4.x.
canonical_html: ./index.html
canonical_markdown: ./index.md
---

[View HTML version](./index.html)

> **Current version** — This documentation describes the current major version of `geo-parser`.
> [View the library roadmap](../index.md)

Lexer and parser library for geographic coordinate strings.

## Installation

```bash
composer require longitude-one/geo-parser:^4.0
```

Collected 4.1.0 installation example:

```bash
composer require longitude-one/geo-parser:4.1.0
```

## Usage

The parser supports two usage patterns. Pass the value to parse to the constructor, then call `parse()` on the
resulting `Parser` object:

```php
use LongitudeOne\GeoParser\Parser;

$input  = '79°56′55″W, 40°26′46″N';

$parser = new Parser($input);

$value = $parser->parse(); // [-79.948611111111, 40.446111111111]
```

When parsing many values, reuse a single `Parser` instance:

```php
use LongitudeOne\GeoParser\Parser;

$input1 = '56.242 E';
$input2 = '40:26:46 S';

$parser = new Parser();

$value1 = $parser->parse($input1); //56.242
$value2 = $parser->parse($input2); //-40.446111111111
```

### Typed coordinates (since 4.0.0)

Since version 4.0.0, use `parseAsCoordinates()` when the parsed value should retain its coordinate structure. It returns a `Coordinate` for a single value and a `Point` for a pair.
An axis is set only when the input contains a cardinal direction; otherwise `getAxis()` returns `null`.

```php
use LongitudeOne\Core\Enum\AxisEnum;
use LongitudeOne\GeoParser\Coordinate;
use LongitudeOne\GeoParser\Parser;
use LongitudeOne\GeoParser\Point;

$coordinate = (new Parser('40°26\'46"N'))->parseAsCoordinates();

assert($coordinate instanceof Coordinate);
assert(40.44611111111111 === $coordinate->getValue());
assert(AxisEnum::LATITUDE === $coordinate->getAxis());

$point = (new Parser('79°56\'55"W, 40°26\'46"N'))->parseAsCoordinates();

assert($point instanceof Point);
assert(-79.94861111111111 === $point->getFirst()->getValue());
assert(AxisEnum::LONGITUDE === $point->getFirst()->getAxis());
assert(AxisEnum::LATITUDE === $point->getSecond()->getAxis());
```

For example, `(new Parser('40, 79'))->parseAsCoordinates()` returns a `Point` whose two coordinates both have a `null` axis.

## Supported Formats

Both single values and coordinate pairs are supported. The following examples illustrate the supported formats; they
are not exhaustive.

A numeric sign may accompany a cardinal direction when both agree: `+40N`, `+75E`, `-40S`, and `-75W`
are accepted. The direction is applied once (`-75W` returns `-75`); conflicting combinations such as `-40N`
or `+75W` throw `UnexpectedValueException`. This also applies to DDM/DMS formats and coordinate pairs,
for both parsing methods. Previously rejected signed cardinal inputs are now accepted when consistent (issue #31).

1. Simple single-signed values

   - 40
   - -40
   - -8.543
   - +132
   - +77.2

1. Simple single signed values with degree symbol

   - 40°
   - -40°
   - -5.234°
   - +43°
   - +38.43°

1. Single unsigned values with or without degree symbol, and cardinal direction

   - 40° N
   - 40 S
   - 56.242 E

1. Single values of signed integer degrees with degree symbol, and decimal minutes with apostrophe

   - 40° 26.222'
   - -65° 32.22'
   - +165° 52.22'

1. Single values of unsigned integer degrees with degree symbol, decimal minutes with apostrophe, and cardinal direction

   - 40° 26.222' E
   - 65° 32.22' S

1. Single values of signed integer degrees with degree symbol, integer minutes with apostrophe, and optional integer or decimal seconds with quote

   - 40° 26' 46"
   - -79° 58' 56"
   - 93° 19' 25.8"
   - +120° 19' 25.8"

1. Single values of signed integer degrees with colon symbol, integer minutes, and optional colon and integer or decimal seconds

   - +40:26:46
   - -79:58:56
   - 93:19:25.8

1. Single values of unsigned integer degrees with degree symbol, integer minutes with apostrophe, optional integer or decimal seconds with quote, and cardinal direction

   - 40° 26' 46" S
   - 99° 58' 56" W
   - 44° 58' 53.9" N

1. Single values of unsigned integer degrees with a colon, integer minutes, optional integer or decimal seconds, and a cardinal direction

   - 40:26:46 S
   - 99:58:56 W
   - 44:58:53.9 N

1. Two of any one format separated by whitespace

1. Two of any one format separated by a comma

## Return

The parser returns an integer or float for a single value, or an array containing a coordinate pair.

String inputs are tokenized and parsed as geographic coordinates. Native integer and float inputs are returned unchanged,
including their type, without passing through the lexer or geographic range validation.

## Exceptions

Untrusted values in exception messages are formatted by spatial-core's `DiagnosticValueFormatter`:
control characters and invalid UTF-8 bytes are escaped, and each value is limited to 2,048 characters.

Library exceptions thrown by the `Lexer` and `Parser` implement the
`LongitudeOne\GeoParser\Exception\ExceptionInterface` interface:

```php
use LongitudeOne\GeoParser\Exception\ExceptionInterface;
use LongitudeOne\GeoParser\Parser;

try {
    $value = (new Parser('100N'))->parse();
} catch (ExceptionInterface $exception) {
    // Handle a library parsing exception.
}
```

## Collected release roadmap

The following table records the collected roadmap; release status is resolved from Packagist by the publication pipeline.

> **Note**
> A major release may increase the minimum supported PHP version. Other breaking changes are documented in the changelog.

| Version | PHP compatibility           | Tested on       | Doctrine Lexer | Tested with Lexer         | Released     | Active Support   | Security fix     |
| ------- | --------------------------- | --------------- | -------------- | ------------------------- | ------------ | ---------------- | ---------------- |
| 3       | 8.1 - 8.2 - 8.3 - 8.4 - 8.5 | From 8.1 to 8.5 | ^2.1 - ^3.0    | 2.1 3.0 3.1-xdev 4.0-xdev | 04 May 2024  | 31 August 2026   | 31 December 2026 |
| 4       | 8.3 - 8.4 - 8.5             | 8.3 - 8.4 - 8.5 | ^3.0.1         | 3.0 3.1-xdev 4.0-xdev     | August 2026  | 31 December 2026 | 31 December 2027 |
| 5       | 8.4 - 8.5                   | 8.4 - 8.5       |                | 3.0 3.1-xdev 4.0-xdev     | January 2027 | 31 December 2027 | 31 December 2028 |
| 6       | 8.5                         | 8.5             |                | 3.0 3.1-xdev 4.0-xdev.    | January 2028 | 31 December 2028 | 31 December 2029 |

PHP versions marked as “tested”, along with every listed Doctrine Lexer version, are part of the continuous integration matrix.

### Support Policy

The non-breaking-change guarantee applies only to the `Lexer` and `Parser` classes. `AxisEnum` is provided by the `longitude-one/spatial-core` dependency.
All other classes are internal implementation details and may change or be removed in any release.

Only the latest major version receives feature and bug fixes. Non-security issues will not be addressed during the security-fixes period.

Previous major versions may receive security fixes only, according to the roadmap above.

## Related documentation

- [Library roadmap](../index.md)
- [Spatial formats](../../concepts/formats.md)