Skip to content

geospatial.md

Latest commit

 

History

History
319 lines (257 loc) · 9.41 KB

geospatial.md

File metadata and controls

319 lines (257 loc) · 9.41 KB

Valkey PHP - Geospatial Indexes

Command Description Supported Tested Class/Trait Method
geoAdd Add one or more geospatial items to the specified key. ✅ ✅ Geospatial geoAdd
geoDist Return the distance between two members in a geospatial set. ✅ ✅ Geospatial geoDist
geoHash Retrieve Geohash strings for one or more elements of a geospatial index. ✅ ✅ Geospatial geoHash
geoPos Return longitude, latitude positions for each requested member. ✅ ✅ Geospatial geoPos
geoRadius Return members of a set with geospatial information that are within the radius specified by the caller. ✅ ✅ Geospatial geoRadius
geoRadiusByMember This method is identical to geoRadius except that instead of passing a longitude and latitude as the "source" you pass an existing member in the geospatial set. ✅ ✅ Geospatial geoRadiusByMember

Usage

$valkey = new Valkey();
$valkey->connect('127.0.0.1', 6379);
$options = ['WITHDIST'];
$valkey->geoAdd('Geospatial', -122.431, 37.773, 'San Francisco');
$valkey->geoAdd('Geospatial', -73.935242, 40.730610, 'New York');
$valkey->geoHash('Geospatial', 'San Francisco');
$valkey->geoPos('Geospatial', 'San Francisco');
$valkey->geoDist('Geospatial', 'San Francisco', 'New York');
$valkey->geoRadius("Geospatial", -157.858, 21.306, 300, 'mi', $options)

geoAdd

Prototype
$valkey->geoAdd($key, $longitude, $latitude, $member [, $longitude, $latitude, $member, ...]);

Description: Add one or more geospatial items to the specified key. This function must be called with at least one longitude, latitude, member triplet.

Return value

Integer: The number of elements added to the geospatial key.

Example
$valkey->del("myplaces");

/* Since the key will be new, $result will be 2 */
$result = $valkey->geoAdd(
    "myplaces",
    -122.431, 37.773, "San Francisco",
    -157.858, 21.315, "Honolulu"
);

geoHash

Prototype
$valkey->geoHash($key, $member [, $member, $member, ...]);

Description: Retrieve Geohash strings for one or more elements of a geospatial index.

Return value

Array: One or more Valkey Geohash encoded strings.

Example
$valkey->geoAdd("hawaii", -157.858, 21.306, "Honolulu", -156.331, 20.798, "Maui");
$hashes = $valkey->geoHash("hawaii", "Honolulu", "Maui");
var_dump($hashes);
Output
array(2) {
  [0]=>
  string(11) "87z9pyek3y0"
  [1]=>
  string(11) "8e8y6d5jps0"
}

geoPos

Prototype
$valkey->geoPos($key, $member [, $member, $member, ...]);

Description: Return longitude, latitude positions for each requested member.

Return value

Array: One or more longitude/latitude positions

Example
$valkey->geoAdd("hawaii", -157.858, 21.306, "Honolulu", -156.331, 20.798, "Maui");
$positions = $valkey->geoPos("hawaii", "Honolulu", "Maui");
var_dump($positions);
Output
array(2) {
  [0]=>
  array(2) {
    [0]=>
    string(22) "-157.85800248384475708"
    [1]=>
    string(19) "21.3060004581273077"
  }
  [1]=>
  array(2) {
    [0]=>
    string(22) "-156.33099943399429321"
    [1]=>
    string(20) "20.79799924753607598"
  }
}

GeoDist

Prototype
$valkey->geoDist($key, $member1, $member2 [, $unit]);

Description: Return the distance between two members in a geospatial set. If units are passed it must be one of the following values:

  • 'm' => Meters
  • 'km' => Kilometers
  • 'mi' => Miles
  • 'ft' => Feet
Return value

Double: The distance between the two passed members in the units requested (meters by default).

Example
$valkey->geoAdd("hawaii", -157.858, 21.306, "Honolulu", -156.331, 20.798, "Maui");

$meters = $valkey->geoDist("hawaii", "Honolulu", "Maui");
$kilometers = $valkey->geoDist("hawaii", "Honolulu", "Maui", 'km');
$miles = $valkey->geoDist("hawaii", "Honolulu", "Maui", 'mi');
$feet = $valkey->geoDist("hawaii", "Honolulu", "Maui", 'ft');

echo "Distance between Honolulu and Maui:\n";
echo "  meters    : $meters\n";
echo "  kilometers: $kilometers\n";
echo "  miles     : $miles\n";
echo "  feet      : $feet\n";

/* Bad unit */
$inches = $valkey->geoDist("hawaii", "Honolulu", "Maui", 'in');
echo "Invalid unit returned:\n";
var_dump($inches);
Output
Distance between Honolulu and Maui:
  meters    : 168275.204
  kilometers: 168.2752
  miles     : 104.5616
  feet      : 552084.0028
Invalid unit returned:
bool(false)

geoRadius

Prototype
$valkey->geoRadius($key, $longitude, $latitude, $radius, $unit [, Array $options]);

Description: Return members of a set with geospatial information that are within the radius specified by the caller.

Options Array

The georadius command can be called with various options that control how Valkey returns results. The following table describes the options valkey-php supports. All options are case insensitive.

Key Value Description
COUNT integer > 0 Limit how many results are returned
WITHCOORD Return longitude and latitude of matching members
WITHDIST Return the distance from the center
WITHHASH Return the raw geohash-encoded score
ASC Sort results in ascending order
DESC Sort results in descending order
STORE key Store results in key
STOREDIST key Store the results as distances in key

Note: It doesn't make sense to pass both ASC and DESC options but if both are passed the last one passed will be used.
Note: When using STORE[DIST] in Valkey Cluster, the store key must has to the same slot as the query key or you will get a CROSSLOT error.

Return value

Mixed: When no STORE option is passed, this function returns an array of results. If it is passed this function returns the number of stored entries.

Example
/* Add some cities */
$valkey->geoAdd("hawaii", -157.858, 21.306, "Honolulu", -156.331, 20.798, "Maui");

echo "Within 300 miles of Honolulu:\n";
var_dump($valkey->geoRadius("hawaii", -157.858, 21.306, 300, 'mi'));

echo "\nWithin 300 miles of Honolulu with distances:\n";
$options = ['WITHDIST'];
var_dump($valkey->geoRadius("hawaii", -157.858, 21.306, 300, 'mi', $options));

echo "\nFirst result within 300 miles of Honolulu with distances:\n";
$options['count'] = 1;
var_dump($valkey->geoRadius("hawaii", -157.858, 21.306, 300, 'mi', $options));

echo "\nFirst result within 300 miles of Honolulu with distances in descending sort order:\n";
$options[] = 'DESC';
var_dump($valkey->geoRadius("hawaii", -157.858, 21.306, 300, 'mi', $options));
Output
Within 300 miles of Honolulu:
array(2) {
  [0]=>
  string(8) "Honolulu"
  [1]=>
  string(4) "Maui"
}

Within 300 miles of Honolulu with distances:
array(2) {
  [0]=>
  array(2) {
    [0]=>
    string(8) "Honolulu"
    [1]=>
    string(6) "0.0002"
  }
  [1]=>
  array(2) {
    [0]=>
    string(4) "Maui"
    [1]=>
    string(8) "104.5615"
  }
}

First result within 300 miles of Honolulu with distances:
array(1) {
  [0]=>
  array(2) {
    [0]=>
    string(8) "Honolulu"
    [1]=>
    string(6) "0.0002"
  }
}

First result within 300 miles of Honolulu with distances in descending sort order:
array(1) {
  [0]=>
  array(2) {
    [0]=>
    string(4) "Maui"
    [1]=>
    string(8) "104.5615"
  }
}

geoRadiusByMember

Prototype
$valkey->geoRadiusByMember($key, $member, $radius, $units [, Array $options]);

Description: This method is identical to geoRadius except that instead of passing a longitude and latitude as the "source" you pass an existing member in the geospatial set.

Options Array

See geoRadius command for options array.

Return value

Array: The zero or more entries that are close enough to the member given the distance and radius specified.

Example
$valkey->geoAdd("hawaii", -157.858, 21.306, "Honolulu", -156.331, 20.798, "Maui");

echo "Within 300 miles of Honolulu:\n";
var_dump($valkey->geoRadiusByMember("hawaii", "Honolulu", 300, 'mi'));

echo "\nFirst match within 300 miles of Honolulu:\n";
var_dump($valkey->geoRadiusByMember("hawaii", "Honolulu", 300, 'mi', ['count' => 1]));
Output
Within 300 miles of Honolulu:
array(2) {
  [0]=>
  string(8) "Honolulu"
  [1]=>
  string(4) "Maui"
}

First match within 300 miles of Honolulu:
array(1) {
  [0]=>
  string(8) "Honolulu"
}