thephpleague/geotools

Geo-related tools PHP 7.3+ library built atop Geocoder and React libraries

Geotools

Geotools is a PHP geo-related library, built atop Geocoder and React libraries.

Features

• Batch geocode & reverse geocoding request(s) in series / in parallel against one or a set of providers. »
• Cache geocode & reverse geocoding result(s) with PSR-6 to improve performances. »
• Compute geocode & reverse geocoding in the command-line interface (CLI) + dumpers and formatters. »
• Accept almost all kind of WGS84 geographic coordinates as coordinates. »
• Support 23 different ellipsoids and it's easy to provide a new one if needed. »
• Convert and format decimal degrees coordinates to decimal minutes or degrees minutes seconds coordinates. »
• Convert decimal degrees coordinates in the Universal Transverse Mercator (UTM) projection. »
• Compute the distance in meter (by default), km, mi or ft between two coordinates using flat, great circle, haversine or vincenty algorithms. »
• Compute the initial and final bearing from the origin coordinate to the destination coordinate in degrees. »
• Compute the initial and final cardinal point (direction) from the origin coordinate to the destination coordinate, read more in wikipedia. »
• Compute the half-way point (coordinate) between the origin and the destination coordinates. »
• Compute the destination point (coordinate) with given bearing in degrees and a distance in meters. »
• Encode a coordinate to a geo hash string and decode it to a coordinate, read more in wikipedia and on geohash.org. »
• Encode a coordinate via the 10:10 algorithm. »
• Polygon class provides methods to check either a poing (coordinate) is in, or on the polygon's boundaries. »
• A command-line interface (CLI) for Distance, Point, Geohash and Convert classes. »
• Integration with Frameworks: Laravel 4, Silex ... »
• ... more to come ...

Installation

Geotools can be found on Packagist. The recommended way to install Geotools is through composer.

Run the following on the command line:

composer require league/geotools

Important: you should use the 0.4 version if you use Geocoder 2.x or/and PHP 5.3.

And install dependencies:

composer install

Now you can add the autoloader, and you will have access to the library:

<?php

require 'vendor/autoload.php';

Usage & API

Coordinate & Ellipsoid

The default geodetic datum is WGS84 and coordinates are in decimal degrees.

Here are the available ellipsoids: AIRY, AUSTRALIAN_NATIONAL, BESSEL_1841, BESSEL_1841_NAMBIA, CLARKE_1866, CLARKE_1880, EVEREST, FISCHER_1960_MERCURY, FISCHER_1968, GRS_1967, GRS_1980, HELMERT_1906, HOUGH, INTERNATIONAL, KRASSOVSKY, MODIFIED_AIRY, MODIFIED_EVEREST, MODIFIED_FISCHER_1960, SOUTH_AMERICAN_1969, WGS60, WGS66, WGS72, and WGS84.

If you need to use an other ellipsoid, just create an array like this:

<?php

$myEllipsoid = \League\Geotools\Coordinate\Ellipsoid::createFromArray([
    'name' => 'My Ellipsoid', // The name of the Ellipsoid
    'a'    => 123.0, // The semi-major axis (equatorial radius) in meters
    'invF' => 456.0 // The inverse flattening
]);

Geotools is built atop Geocoder. It means it's possible to use the \Geocoder\Model\Address directly but it's also possible to use a string or a simple array with its latitude and longitude.

It supports valid and acceptable geographic coordinates like:

• 40:26:46N,079:56:55W
• 40:26:46.302N 079:56:55.903W
• 40°26′47″N 079°58′36″W
• 40d 26′ 47″ N 079d 58′ 36″ W
• 40.446195N 79.948862W
• 40.446195, -79.948862
• 40° 26.7717, -79° 56.93172

Latitudes below -90.0 or above 90.0 degrees are capped through \League\Geotools\Coordinate\Coordinate::normalizeLatitude(). Longitudes below -180.0 or above 180.0 degrees are wrapped through \League\Geotools\Coordinate\Coordinate::normalizeLongitude().

<?php

use League\Geotools\Coordinate\Coordinate;
use League\Geotools\Coordinate\Ellipsoid;

// from an \Geocoder\Model\Address instance within Airy ellipsoid
$coordinate = new Coordinate($geocoderResult, Ellipsoid::createFromName(Ellipsoid::AIRY));
// or in an array of latitude/longitude coordinate within GRS 1980 ellipsoid
$coordinate = new Coordinate([48.8234055, 2.3072664], Ellipsoid::createFromName(Ellipsoid::GRS_1980));
// or in latitude/longitude coordinate within WGS84 ellipsoid
$coordinate = new Coordinate('48.8234055, 2.3072664');
// or in degrees minutes seconds coordinate within WGS84 ellipsoid
$coordinate = new Coordinate('48°49′24″N, 2°18′26″E');
// or in decimal minutes coordinate within WGS84 ellipsoid
$coordinate = new Coordinate('48 49.4N, 2 18.43333E');
// the result will be:
printf("Latitude: %F\n", $coordinate->getLatitude()); // 48.8234055
printf("Longitude: %F\n", $coordinate->getLongitude()); // 2.3072664
printf("Ellipsoid name: %s\n", $coordinate->getEllipsoid()->getName()); // WGS 84
printf("Equatorial radius: %F\n", $coordinate->getEllipsoid()->getA()); // 6378136.0
printf("Polar distance: %F\n", $coordinate->getEllipsoid()->getB()); // 6356751.317598
printf("Inverse flattening: %F\n", $coordinate->getEllipsoid()->getInvF()); // 298.257224
printf("Mean radius: %F\n", $coordinate->getEllipsoid()->getArithmeticMeanRadius()); // 6371007.772533
// it's also possible to modify the coordinate without creating an other coodinate
$coordinate->setFromString('40°26′47″N 079°58′36″W');
printf("Latitude: %F\n", $coordinate->getLatitude()); // 40.446388888889
printf("Longitude: %F\n", $coordinate->getLongitude()); // -79.976666666667

Convert

It provides methods (and aliases) to convert decimal degrees WGS84 coordinates to degrees minutes seconds or decimal minutes WGS84 coordinates. You can format the output string easily.

You can also convert them in the Universal Transverse Mercator (UTM) projection (Southwest coast of Norway and the region of Svalbard are covered).

<?php

$geotools   = new \League\Geotools\Geotools();
$coordinate = new \League\Geotools\Coordinate\Coordinate('40.446195, -79.948862');
$converted  = $geotools->convert($coordinate);
// convert to decimal degrees without and with format string
printf("%s\n", $converted->toDecimalMinutes()); // 40 26.7717N, -79 56.93172W
// convert to degrees minutes seconds without and with format string
printf("%s\n", $converted->toDegreesMinutesSeconds('<p>%P%D:%M:%S, %p%d:%m:%s</p>')); // <p>40:26:46, -79:56:56</p>
// convert in the UTM projection (standard format)
printf("%s\n", $converted->toUniversalTransverseMercator()); // 17T 589138 4477813

Here is the mapping:

Decimal minutes	Latitude	Longitude
Positive or negative sign	%P	%p
Direction	%L	%l
Degrees	%D	%d
Decimal minutes	%N	%n

Degrees minutes seconds	Latitude	Longitude
Positive or negative sign	%P	%p
Direction	%L	%l
Degrees	%D	%d
Minutes	%M	%m
Seconds	%S	%s

Batch

It provides a very handy way to batch geocode and reverse geocoding requests in serie or in parallel against a set of providers. Thanks to Geocoder and React libraries.

It's possible to batch one request (a string) or a set of request (an array) against one provider or set of providers.

You can use a provided cache engine or use your own by setting a cache object which should implement League\Geotools\Cache\CacheInterface and extend League\Geotools\Cache\AbstractCache if needed.

At the moment Geotools supports any PSR-6 cache.

NB: Before you implement caching in your app please be sure that doing so does not violate the Terms of Service for your(s) geocoding provider(s).

<?php

$geocoder = new \Geocoder\ProviderAggregator(); // or \Geocoder\TimedGeocoder
$httpClient  = HttpClientDiscovery::find();

$geocoder->registerProviders([
    new \Geocoder\Provider\GoogleMaps\GoogleMaps($httpClient),
    new \Geocoder\Provider\OpenStreetMap\OpenStreetMap($httpClient),
    new \Geocoder\Provider\BingMaps\BingMaps($httpClient, '<FAKE_API_KEY>'), // throws InvalidCredentialsException
    new \Geocoder\Provider\Yandex\Yandex($httpClient),
    new \Geocoder\Provider\FreeGeoIp\FreeGeoIp($httpClient),
    new \Geocoder\Provider\Geoip\Geoip(),
]);

try {
    $geotools = new \League\Geotools\Geotools();
    $cache    = new \Cache\Adapter\PHPArray\ArrayCachePool();

    $results  = $geotools->batch($geocoder)->setCache($cache)->geocode([
        'Paris, France',
        'Copenhagen, Denmark',
        '74.200.247.59',
        '::ffff:66.147.244.214'
    ])->parallel();
} catch (\Exception $e) {
    die($e->getMessage());
}

$dumper = new \Geocoder\Dumper\WktDumper();
foreach ($results as $result) {
    // if a provider throws an exception (UnsupportedException, InvalidCredentialsException ...)
    // an custom /Geocoder/Result/Geocoded instance is returned which embedded the name of the provider,
    // the query string and the exception string. It's possible to use dumpers
    // and/or formatters from the Geocoder library.
    printf("%s|%s|%s\n",
        $result->getProviderName(),
        $result->getQuery(),
        '' == $result->getExceptionMessage() ? $dumper->dump($result) : $result->getExceptionMessage()
    );
}

You should get 24 results (4 values to geocode against 6 providers) something like:

google_maps|Paris, France|POINT(2.352222 48.856614)
google_maps|Copenhagen, Denmark|POINT(12.568337 55.676097)
google_maps|74.200.247.59|The GoogleMapsProvider does not support IP addresses.
google_maps|::ffff:66.147.244.214|The GoogleMapsProvider does not support IP addresses.
openstreetmap|Paris, France|POINT(2.352133 48.856506)
openstreetmap|Copenhagen, Denmark|POINT(12.570072 55.686724)
openstreetmap|74.200.247.59|Could not execute query http://nominatim.openstreetmap.org/search?q=74.200.247.59&format=xml&addressdetails=1&limit=1
openstreetmap|::ffff:66.147.244.214|The OpenStreetMapProvider does not support IPv6 addresses.
bing_maps|Paris, France|Could not execute query http://dev.virtualearth.net/REST/v1/Locations/?q=Paris%2C+France&key=<FAKE_API_KEY>
bing_maps|Copenhagen, Denmark|Could not execute query http://dev.virtualearth.net/REST/v1/Locations/?q=Copenhagen%2C+Denmark&key=<FAKE_API_KEY>
bing_maps|74.200.247.59|The BingMapsProvider does not support IP addresses.
bing_maps|::ffff:66.147.244.214|The BingMapsProvider does not support IP addresses.
yandex|Paris, France|POINT(2.341198 48.856929)
yandex|Copenhagen, Denmark|POINT(12.567602 55.675682)
yandex|74.200.247.59|The YandexProvider does not support IP addresses.
yandex|::ffff:66.147.244.214|The YandexProvider does not support IP addresses.
free_geo_ip|Paris, France|The FreeGeoIpProvider does not support Street addresses.
free_geo_ip|Copenhagen, Denmark|The FreeGeoIpProvider does not support Street addresses.
free_geo_ip|74.200.247.59|POINT(-122.415600 37.748400)
free_geo_ip|::ffff:66.147.244.214|POINT(-111.613300 40.218100)
geoip|Paris, France|The GeoipProvider does not support Street addresses.
geoip|Copenhagen, Denmark|The GeoipProvider does not support Street addresses.
geoip|74.200.247.59|POINT(-122.415604 37.748402)
geoip|::ffff:66.147.244.214|The GeoipProvider does not support IPv6 addresses.

Batch reverse geocoding is something like:

<?php

// ... $geocoder like the previous example ...
// If you want to reverse one coordinate
try {
    $results = $geotools->batch($geocoder)->reverse(
        new \League\Geotools\Coordinate\Coordinate([2.307266, 48.823405])
    )->parallel();
} catch (\Exception $e) {
    die($e->getMessage());
}
// Or if you want to reverse geocoding 3 coordinates
$coordinates = [
    new \League\Geotools\Coordinate\Coordinate([2.307266, 48.823405]),
    new \League\Geotools\Coordinate\Coordinate([12.568337, 55.676097]),
    new \League\Geotools\Coordinate\Coordinate('-74.005973 40.714353')),
];
$results = $geotools->batch($geocoder)->reverse($coordinates)->parallel();
// ...

If you want to batch it in serie, replace the method parallel() by serie().

To optimize batch requests you need to register providers according to their capabilities and what you're looking for (geocode street addresses, geocode IPv4, geocode IPv6 or reverse geocoding), please read more at the Geocoder library doc.

Distance

It provides methods to compute the distance in meter (by default), km, mi or ft between two coordinates using flat (most performant), great circle, haversine or vincenty (most accurate) algorithms.

Those coordinates should be in the same ellipsoid.

<?php

$geotools = new \League\Geotools\Geotools();
$coordA   = new \League\Geotools\Coordinate\Coordinate([48.8234055, 2.3072664]);
$coordB   = new \League\Geotools\Coordinate\Coordinate([43.296482, 5.36978]);
$distance = $geotools->distance()->setFrom($coordA)->setTo($coordB);

printf("%s\n",$distance->flat()); // 659166.50038742 (meters)
printf("%s\n",$distance->greatCircle()); // 659021.90812846
printf("%s\n",$distance->in('km')->haversine()); // 659.02190812846
printf("%s\n",$distance->in('mi')->vincenty()); // 409.05330679648
printf("%s\n",$distance->in('ft')->flat()); // 2162619.7519272

Point

It provides methods to compute the initial and final bearing in degrees, the initial and final cardinal direction, the middle point and the destination point. The middle and the destination points returns a \League\Geotools\Coordinate\Coordinate object with the same ellipsoid.

<?php

$geotools = new \League\Geotools\Geotools();
$coordA   = new \League\Geotools\Coordinate\Coordinate([48.8234055, 2.3072664]);
$coordB   = new \League\Geotools\Coordinate\Coordinate([43.296482, 5.36978]);
$vertex    =  $geotools->vertex()->setFrom($coordA)->setTo($coordB);

printf("%d\n", $vertex->initialBearing()); // 157 (degrees)
printf("%s\n", $vertex->initialCardinal()); // SSE (SouthSouthEast)
printf("%d\n", $vertex->finalBearing()); // 160 (degrees)
printf("%s\n", $vertex->finalCardinal()); // SSE (SouthSouthEast)

$middlePoint = $vertex->middle(); // \League\Geotools\Coordinate\Coordinate
printf("%s\n", $middlePoint->getLatitude()); // 46.070143125815
printf("%s\n", $middlePoint->getLongitude()); // 3.9152401085931

$destinationPoint = $geotools->vertex()->setFrom($coordA)->destination(180, 200000); // \League\Geotools\Coordinate\Coordinate
printf("%s\n", $destinationPoint->getLatitude()); // 47.026774650075
printf("%s\n", $destinationPoint->getLongitude()); // 2.3072664

Geohash

It provides methods to get the geo hash and its bounding box's coordinates (SouthWest & NorthEast) of a coordinate and the coordinate and its bounding box's coordinates (SouthWest & NorthEast) of a geo hash.

<?php

$geotools       = new \League\Geotools\Geotools();
$coordToGeohash = new \League\Geotools\Coordinate\Coordinate('43.296482, 5.36978');

// encoding
$encoded = $geotools->geohash()->encode($coordToGeohash, 4); // 12 is the default length / precision
// encoded
printf("%s\n", $encoded->getGeohash()); // spey
// encoded bounding box
$boundingBox = $encoded->getBoundingBox(); // array of \League\Geotools\Coordinate\CoordinateInterface
$southWest   = $boundingBox[0];
$northEast   = $boundingBox[1];
printf("http://www.openstreetmap.org/?minlon=%s&minlat=%s&maxlon=%s&maxlat=%s&box=yes\n",
    $southWest->getLongitude(), $southWest->getLatitude(),
    $northEast->getLongitude(), $northEast->getLatitude()
); // http://www.openstreetmap.org/?minlon=5.2734375&minlat=43.2421875&maxlon=5.625&maxlat=43.41796875&box=yes

// decoding
$decoded = $geotools->geohash()->decode('spey61y');
// decoded coordinate
printf("%s\n", $decoded->getCoordinate()->getLatitude()); // 43.296432495117
printf("%s\n", $decoded->getCoordinate()->getLongitude()); // 5.3702545166016
// decoded bounding box
$boundingBox = $decoded->getBoundingBox(); //array of \League\Geotools\Coordinate\CoordinateInterface
$southWest   = $boundingBox[0];
$northEast   = $boundingBox[1];
printf("http://www.openstreetmap.org/?minlon=%s&minlat=%s&maxlon=%s&maxlat=%s&box=yes\n",
    $southWest->getLongitude(), $southWest->getLatitude(),
    $northEast->getLongitude(), $northEast->getLatitude()
); // http://www.openstreetmap.org/?minlon=5.3695678710938&minlat=43.295745849609&maxlon=5.3709411621094&maxlat=43.297119140625&box=yes

You can also get information about neighbor points (image).

<?php

$geotools = new \League\Geotools\Geotools();

// decoding
$decoded = $geotools->geohash()->decode('spey61y');
// get neighbor geohash
printf("%s\n", $decoded->getNeighbor(\League\Geotools\Geohash\Geohash::DIRECTION_NORTH)); // spey64n
printf("%s\n", $decoded->getNeighbor(\League\Geotools\Geohash\Geohash::DIRECTION_SOUTH_EAST)); // spey61x
// get all neighbor geohashes
print_r($decoded->getNeighbors(true));
/**
 * Array
 * (
 *     [north] => spey64n
 *     [south] => spey61w
 *     [west] => spey61v
 *     [east] => spey61z
 *     [north_west] => spey64j
 *     [north_east] => spey64p
 *     [south_west] => spey61t
 *     [south_east] => spey61x
 * )
 */

10:10

Represent a location with 10m accuracy using a 10 character code that includes features to prevent errors in entering the code. Read more about the algorithm here.

<?php

$tenten = new \League\Geotools\Tests\Geohash\TenTen;
$tenten->encode(new Coordinate([51.09559, 1.12207])); // MEQ N6G 7NY5

Vertex

Represents a segment with a direction. You can find if two vertexes are on the same line.

<?php
	$vertexA->setFrom(48.8234055);
	$vertexA->setTo(2.3072664);

	$vertexB->setFrom(48.8234055);
	$vertexB->setTo(2.3072664);
	$vertexA->isOnSameLine($vertexB);

Polygon

It helps you to know if a point (coordinate) is in a Polygon or on the Polygon's boundaries and if this in on a Polygon's vertex.

First you need to create the polygon, you can provide:

• an array of arrays
• an array of Coordinate
• a CoordinateCollection

<?php

$polygon = new \League\Geotools\Polygon\Polygon([
    [48.9675969, 1.7440796],
    [48.4711003, 2.5268555],
    [48.9279131, 3.1448364],
    [49.3895245, 2.6119995],
]);

$polygon->setPrecision(5); // set the comparision precision
$polygon->pointInPolygon(new \League\Geotools\Coordinate\Coordinate([49.1785607, 2.4444580])); // true
$polygon->pointInPolygon(new \League\Geotools\Coordinate\Coordinate([49.1785607, 5])); // false
$polygon->pointOnBoundary(new \League\Geotools\Coordinate\Coordinate([48.7193486, 2.13546755])); // true
$polygon->pointOnBoundary(new \League\Geotools\Coordinate\Coordinate([47.1587188, 2.87841795])); // false
$polygon->pointOnVertex(new \League\Geotools\Coordinate\Coordinate([48.4711003, 2.5268555])); // true
$polygon->pointOnVertex(new \League\Geotools\Coordinate\Coordinate([49.1785607, 2.4444580])); // false
$polygon->getBoundingBox(); // return the BoundingBox object

CLI

It provides command lines to compute methods provided by Distance, Point, Geohash and Convert classes. Thanks to the Symfony Console Component.

$ php geotools list // list of available commands
$ php geotools help distance:flat // get the help
$ php geotools distance:flat "40° 26.7717, -79° 56.93172" "30°16′57″N 029°48′32″W" // 4690203.1048522
$ php geotools distance:haversine "35,45" "45,35" --ft  // 4593030.9787593
$ php geotools distance:vincenty "35,45" "45,35" --km  // 1398.4080717661
$ php geotools d:v "35,45" "45,35" --km --ellipsoid=WGS60 // 1398.4145201642
$ php geotools point:initial-cardinal "40:26:46.302N 079:56:55.903W" "43.296482, 5.36978" // NE (NordEast)
$ php geotools point:final-cardinal "40:26:46.302N 079:56:55.903W" "43.296482, 5.36978" // ESE (EastSouthEast)
$ php geotools point:destination "40° 26.7717, -79° 56.93172" 25 10000 // 40.527599285543, -79.898914904538
$ php geotools p:d "40° 26.7717, -79° 56.93172" 25 10000 --ellipsoid=GRS_1980 // 40.527599272782, -79.898914912379
$ php geotools geohash:encode "40° 26.7717, -79° 56.93172" --length=3 // dpp
$ php geotools convert:dm "40.446195, -79.948862" --format="%P%D°%N %p%d°%n" // 40°26.7717 -79°56.93172
$ php geotools convert:dms "40.446195, -79.948862" --format="%P%D:%M:%S, %p%d:%m:%s" // 40:26:46, -79:56:56
$ php geotools convert:utm "60.3912628, 5.3220544" // 32V 297351 6700644
$ php geotools c:u "60.3912628, 5.3220544" --ellipsoid=AIRY // 32V 297371 6700131
...

Compute street addresses, IPv4s or IPv6s geocoding and reverse geocoding right in your console.

It's possible to define and precise your request through these options:

• --provider: bing_maps, yahoo, maxmind... google_maps is the default one. See the full list here.
• --raw: the result output in RAW format, shows Adapter, Provider and Arguments if any.
• --json: the result output in JSON string format.
• --args: this option accepts multiple values (e.g. --args="API_KEY" --args="LOCALE") if your provider needs or can have arguments.
• --dumper: this option is available for geocoding, gpx, geojson, kml, wkb and wkt by default. Read more here.
• --format: this option is available for reverse geocoding, see the mapping here.

$ php geotools help geocoder:geocode // get the help
$ php geotools geocoder:geocode "Copenhagen, Denmark" // 55.6760968, 12.5683371
$ php geotools geocoder:geocode "74.200.247.59" --provider="free_geo_ip" // 37.7484, -122.4156
$ php geotools geocoder:geocode Paris --args="fr_FR" --args="France" --args="true" // 48.856614, 2.3522219
$ php geotools geocoder:geocode Paris --dumper=wkt // POINT(2.352222 48.856614)
...
$ php geotools geocoder:reverse "48.8631507, 2.388911" // Avenue Gambetta 10, 75020 Paris
$ php geotools geocoder:reverse "48.8631507, 2.388911" --format="%L, %A1, %C" // Paris, Île-De-France, France
$ php geotools geocoder:reverse "48.8631507, 2.388911" --format="%L, %A1, %C" --provider="openstreetmap"
// Paris, Île-De-France, France Métropolitaine
...
$ php geotools geocoder:geocode "Tagensvej 47, Copenhagen" --raw --args=da_DK --args=Denmark

The last command will show an output like this:

HttpClient:    \Http\Client\Curl\Client
Provider:      \Geocoder\Provider\GoogleMaps
Cache:         \League\Geotools\Cache\Redis
Arguments:     da_DK,Denmark
---
Latitude:      55.699953
Longitude:     12.552736
Bounds
 - South: 55.699953
 - West:  12.552736
 - North: 55.699953
 - East:  12.552736
Street Number: 47
Street Name:   Tagensvej
Zipcode:       2200
City:          Copenhagen
City District: København N
County:        København
County Code:   KØBENHAVN
Region:        Capital Region Of Denmark
Region Code:   CAPITAL REGION OF DENMARK
Country:       Denmark
Country Code:  DK
Timezone:

Integration with Frameworks

• Laravel 4 & 5
• Silex
• ...

Unit Tests

To run unit tests, you'll need the cURL extension and a set of dependencies, you can install them using Composer:

$ php composer.phar install --dev

Once installed, just launch the following command:

$ phpunit --coverage-text

Credits

• Antoine Corcy
• Pascal Borreli
• Phil Sturgeon
• Gabriel Bull
• All contributors

Acknowledgments

• Geocoder - MIT
• ReactPHP - MIT
• Symfony Console Component - MIT
• Symfony Serializer Component - MIT
• PHP client library for Redis - MIT
• Geokit, Geotools-for-CodeIgniter, geotools-php ...

Changelog

See the changelog file

Contributing

Please see CONTRIBUTING for details.

Support

Bugs and feature request are tracked on GitHub

Contributor Code of Conduct

As contributors and maintainers of this project, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting pull requests or patches, and other activities.

We are committed to making participation in this project a harassment-free experience for everyone, regardless of level of experience, gender, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, age, or religion.

Examples of unacceptable behavior by participants include the use of sexual language or imagery, derogatory comments or personal attacks, trolling, public or private harassment, insults, or other unprofessional conduct.

Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct. Project maintainers who do not follow the Code of Conduct may be removed from the project team.

Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by opening an issue or contacting one or more of the project maintainers.

This Code of Conduct is adapted from the Contributor Covenant, version 1.0.0, available at https://contributor-covenant.org/version/1/0/0/

License

Geotools is released under the MIT License. See the bundled LICENSE file for details.

geotools's Issues

Would OSGB conversions be appropriate?

Would OSGB to UTM conversions be appropriate to this library, or is it out of scope?
OSGB is a grid system used in the UK and developed by Ordnance Survey (OS). A conversion of OS data to UTM, and back again, would be very useful.

See http://en.wikipedia.org/wiki/Ordnance_Survey_National_Grid

Just testing the water to see if national grid systems is something you want to support. I've had to do conversions on data like this in the past, and will have some code from years ago, tucked away somewhere (I needed to convert postcode locations from OSGB formats). I expect there would be others from other regions and nations, once that gate is open.

Natural Area Code

http://en.wikipedia.org/wiki/Natural_Area_Code

Cache adapter for Credis library

A lot of Magento 1 projects use the Credis library, due its use as a cache and sessions backend in popular extensions that are now included in its core. It would be nice if there was an adapter for Credis to sit alongside the Predis adapter, so that an existing Credis_Client object could be passed in and used as a cache.

See https://github.com/colinmollenhour/credis

I am happy to develop this adapter, and am mostly putting this forward to discuss what the name of the class for this adapter should be so as to avoid naming conflicts with the existing Predis adapter.

Add Geometry class

• polygon's centroïd
• bounding box of a polygon
• create a polygon from an array for coordinates
• are 2 lines crossing each other ?
• ...

Geohash Integer methods

It would be quite nice to allow encoding into geohash integers.

For example https://github.com/sunng87/node-geohash offers the encode_int = function (latitude, longitude, bitDepth) function.

Since the current Geohash implemenation manages state inside the class and is not like a static converter class, the way to go would be a new GehashInteger class, right?

Or does it make sense to refactor the the current Geohash class to support additional converting methods for geohash integers?

EDIT: Better description

cheers mablae

Add service provider to Silex

Packagist not to date with current tag

it seems packagist is always one tag behind current.

Could you please check that the webhook is properly configured?

Add help and command exemples to CLI

like php geotools help geocoder:g and php geotools help geocoder:r.

Add tests to cache classes

How to find out who provided geolocation using ChainProvider

Hi,
can I find out which provider provided geolocation for each address when I use ChainProvider? When I try something like this:

$geocoder->registerProvider(new ChainProvider(array(
    new GoogleMapsProvider($adapter, null, null, true, $this->googleApiKey),
    new MapQuestProvider($adapter, $this->mapQuestKey),
    new YandexProvider($adapter),
    new NominatimProvider($adapter, 'http://nominatim.openstreetmap.org'),
)));
$geotools = new \League\Geotools\Geotools();
$geocoded = $geotools->batch($geocoder)->geocode($locationsToSave)->parallel();
foreach ($geocoded as $g) {
    echo $g->provider;
}

I get only "chain" for all addresses. And I'm not sure if it is bug or feature. ;o)

Thanks.

Add redis cache

Compatibility with Symfony 3.0

Geotools depends on symfony/serializer ~2.7, which means symfony/serializer >=2,7, <3.0.

This makes impossible to use Geotools in a Symfony 3.0 project.

Add support of different Ellipsoid to CLI

Precision and scale of Coordinates

I want to save the Coordinate in a database with Doctrine2 under Symfony.

That because I need to know the required scale and precision for the coordinate.
Which is the best scale and precision for longitude and latitude?

Currently I have this:

    /**
     * @ORM\Column(type="decimal", precision=10, scale=6, nullable=true)
     */
    private $latitude;

    /**
     * @ORM\Column(type="decimal", precision=10, scale=6, nullable=true)
     */
    private $longitude;

Is this precision and scale ok?

Maybe this should be written on README.md for other users.

Feature: Voronoi Diagram

http://en.wikipedia.org/wiki/Voronoi_diagram
https://www.youtube.com/watch?v=90NsjKvz9Ns&feature=youtu.be

Add TomTom provider to CLI

If this PR is merged and when a new version of Geocoder will be released.

Support for different ellipsoids

To get more more accurate results.

Caching

To improve batch geocode & reverse geociding requests.

Maybe an interface which will implement methods like this:

• set a tuple key, value
• get a tuple by a key
• list of tuples
• delete a tuple
• flush all tuples
• ...

Memcached, MangoDB, Redis...

Is a coordinate in a bounding box / geohash ?

Website

http://geotools-php.org/

Boost symfony/console version to ~3.*

Had to downgrade it in my project to use this package.

What if someone uses 3.* features and can't drop them ?

Division by zero

There's a division by zero when calculating distance in miles (perhaps doesn't depend on units) with vincenty algorithm, specifically when trying to calculate distance from between two same coordinates.

Code to reproduce:

<?php

$geotools = new \League\Geotools\Geotools();
$coordA   = new \League\Geotools\Coordinate\Coordinate(array(48.8234055, 2.3072664));
$coordB   = new \League\Geotools\Coordinate\Coordinate(array(48.8234055, 2.3072664));
$distance = $geotools->distance()->setFrom($coordA)->setTo($coordB);

printf("%s\n",$distance->in('mi')->vincenty()); // 0
// WARNING: Division by zero line: 192 file: vendor/league/geotools/src/League/Geotools/Distance/Distance.php

Please let me know if you need any additional information. If I find some time I'll submit a pull request with a patch for this one... Thank you!

Add bundle to Symfony2

Limit for parallel requests?

Hi,

is there any limit for maximum number of requests sent in parallel or does the library handle it internally? My concern is, what would happen if I put hundreds of addresses to Batch::geocode()? Will be all of them called at once? I am afraid that at least some APIs wouldn't like it. ;o) I am sorry but I am not able to get it from source code, React is quite a new thing for me.

Thanks.

MySQL (PDO ?) cache support

Hello,

is there a chance MySQL cache will get's it's place in this package too?

Thank you

Geohash-36

• http://en.wikipedia.org/wiki/Geohash-36
• https://sites.google.com/site/openpostcode/other-codes/geohash-36
• https://sites.google.com/site/openpostcode/home/calculations
• http://geo36.org/

Military grid reference system

http://en.wikipedia.org/wiki/Military_grid_reference_system

Add IpGeoBase and Baidu as available providers

If PRs are merged:

• geocoder-php/Geocoder#208
• geocoder-php/Geocoder#210

Add expire value to caches

Possibly use a cache in the CLI for geocoder

I would love to see an option (on by default?) to use a cache in the CLI for geocoder.

geotools --cache=yes geocoder:geocode "My Favorite Hiding Place"

normalizeLatitude and normalizeLongitude examples in docs don't work as-is

From the README:

Latitudes below -90.0 or above 90.0 degrees are capped through
\League\Geotools\Coordinate\Coordinate::normalizeLatitude().
Longitudes below -180.0 or abode 180.0 degrees are wrapped through
\League\Geotools\Coordinate\Coordinate::normalizeLongitude().

However, when called this way:

Non-static method League\Geotools\Coordinate\Coordinate::normalizeLatitude() should not be called statically

Source has them as plain public methods. So either the source should change (PR submitted) or the docs should.

Should memcache be implemented ?

http://fr.php.net/manual/fr/book.memcache.php

Password authentication to MangoDB and Redis

Improve Batch class

When we batch for exemple 2 street addresses against 2 providers, the result is not really clear because it doesn't embed the provider name either the request.

Add service provider to Laravel 4

Add a "createFromFormat" method

Hi,

it would be nice to have a Coordinate::createFromFormat() method (similar to DateTime::createFromFormat() -
http://www.php.net/manual/en/datetime.createfromformat.php).

I'm indeed having issues with the Coordinate::toDecimalDegrees() not parsing properly those coordinates :

25°59.86'N,21°09.81'W
25°59.860'N,21°09.810'W

These are parsed by the last regex (Degrees Minutes Seconds) of toDecimalDegrees while they really should be parsed by the one before (DD°MM.mmm).

Given that you already have a mapping for outputting the coordinates, it would be great to be able to use the same mappings for input!

I've played around with the test cases already and will try to provide a PR.

Add memcached cache

Using geocoder 3.x

Is this in the plans? Would you accept a PR for this?

Add bounding box class

Mini-Site

Would you be up for making a branded mini-site, like some of the other League packages?

http://platesphp.com/
http://fractal.thephpleague.com/
http://flysystem.thephpleague.com/

You can look at the sculpin branch for fractal, which is the source with a bunch of PHP.

Get started with sculpin here.

Source goes in sculpin, then the website is pushed to gh-pages. Tweak the deploy.sh to have your information in there, then all you need to do is point the DNS to GitHub.

Hit me up on email/skype any time if you want help with this.

Geohash->encode() can't be called twice on same object

For the matter of performance, I don't want to create a new Geohash object within a large for loop encoding thousands of coordinates to their respective geohashes. But as far as I can see, it's methods are not meant to be called twice.

Example:

use League\Geotools\Geohash\Geohash;

$Hash = new Geohash();
echo $Hash->encode(new Coordinate(array(0, 0)), 12); // prints "7zzzzzzzzzzz" as expected
echo $Hash->encode(new Coordinate(array(49, 7)), 12); // still prints "7zzzzzzzzzzz" instead of "u0syz21jxy43"

Looking at the code, that's quite obvious. First of all, latitude and longitude interval are used from the previous encoding (see Geohash.php#L134-L135) and the geohash is never set back to an empty string.

Is there any reason for that?

Add international feet unit to CLI + test

Division by zero

Hello,

using this library ("version": "0.4.0") i found a division by zero when calculating distance with vincenty algorithm, when both points have latitude 0 (stand on equator)

here the code:

$geotools = new \League\Geotools\Geotools();
$coordA   = new \League\Geotools\Coordinate\Coordinate(array(0, 30));
$coordB   = new \League\Geotools\Coordinate\Coordinate(array(0, 20));

$distance = $geotools->distance()->setFrom($coordA)->setTo($coordB)->in('km')->vincenty();
//Division by zero in vendor/league/geotools/src/Distance/Distance.php:194 {$cos2SigmaM = $cosSigma - 2 * $sinU1 * $sinU2 / $cosSqAlpha;}

Please let me know if you need additional info.

"Point" terminology

An instance of the Point class has an origin and a destination coordinate. This seems like poor naming, as in most GIS implementations (and semantically) a point has exactly 1 coordinate.

Having a quick Google around, either MultiPoint or Line would make more sense, although these are generally not limited to 2 coordinates.

Maybe I'm viewing the class wrongly and it shouldn't be thought of a value object at all but a coordinate service / calculator. In that case perhaps Point should be in a different namespace that implies it's a tool rather than a value object, which is what Convert does.

Feel free to close as wontfix, as I guess "geotools" implies that this is a collection of tools, as opposed to a component to drop into the business domain.

Add arcgis_online if merged

geocoder-php/Geocoder#215

Symfony2 Bundle and Doctrine Integration?

Is there any Symfony2 Bundle for this? What's about integration for Doctrine2?

I want to save coordinates to the database with Doctrine2 and get results based on distance.

Add Polygon documentation

Here: https://github.com/thephpleague/geotools#polygon
PR: #44

Clear exception if provider limit occurs

Is there any clear exception which will be thrown if the provider limits has been reached?

For example Google Maps Geocoding API limits:
https://developers.google.com/maps/documentation/geocoding/intro#Limits

I want to stop my script in a nice way if this limit occurs so I need a clear way to know if this limit is reached. How to handle it the right way?

Special characters for geocoding over cli

geocoder:geocode "Berlin Hauptstraße 1"

[Geocoder\Exception\NoResultException]                                       
Could not execute query http://maps.googleapis.com/maps/api/geocode/json?address=Berlin%20Hauptstra%DFe%201

10:10 Code

• http://blog.jgc.org/2010/06/1010-code.html
• http://blog.jgc.org/2006/07/simple-code-for-entering-latitude-and.html