geo2code - latitude/longitude encoding for regional search

SYNOPSIS

<geo2code $lat $lon [$radius]>

DESCRIPTION
Note: geo2code is a deprecated function. Use the SQL functions latlon2geocode() and latlon2geocodebox() where possible instead.

The geo2code function encodes each latitude/longitude coordinate given into one integer. This number can be indexed and used with a special variant of Texis' between operator for bounded-box searches of a geographical region. The $lat, $lon and optional $radius parameters are integers in the form DDDMMSS (DMS "degrees minutes seconds" format), with negative numbers representing south latitudes and east longitudes respectively (note that longitude signs are the opposite of ISO 6709, which is east-positive).

Valid values for $lat are -90 to 90 degrees inclusive (i.e. -900000 to 900000). Valid values for $lon are -360 to 360 degrees inclusive. A $lon value less than -180 degrees will have 360 degrees added to it, and a $lon value greater than 180 degrees will have 360 degrees subtracted from it. This allows longitude values to continue to increase or decrease when crossing the International Dateline, and thus avoid a non-linear "step function". Passing invalid $lat or $lon values will return -1. These changes were added in version 5.01.1193955804 20071101.

By using this encoding method and a special variant of the between operator, only one field need be indexed and searched, instead of both latitude and longitude separately, which can be time-consuming at search. The encoded position can be decoded back to latitude/longitude with the code2geo function (here).

If the optional $radius parameter is given, then a pair of numbers is returned for each coordinate. The pair represents the encoding for the NW and SE corners of a box that is twice the $radius in length on a side, with the given coordinate at the center. The pair is returned as a comma-separated parenthetical string. The result can thus be directly inserted into a SQL statement to search the geographical region within $radius DDDMMSS of the given coordinate (DMS "degrees minutes seconds" format). Where available, the latlon2geocodearea() SQL function is preferred however, as it returns a true parameter, not SQL statement fragment.

DIAGNOSTICS
geo2code returns a long integer for each latitude/longitude coordinate pair given, for a BETWEEN(aaa, bbb) GIS search. If a $radius argument is given, geo2code returns a comma-separated parenthetical pair of numbers instead, for the bounding box that contains a circle of that radius centered on the point. All arguments are Texis/Vortex DDDMMSS integers (DMS "degrees minutes seconds" format, west-positive).

EXAMPLE
In this example, latitude/longitude positions for cities were encoded with geo2code into the GeoCode field of a table. A $latitude and $longitude are passed to this function (e.g. from a form) and used to search for cities in a boxed geographic region centered on the given coordinate:

<A NAME=search>
  Cities within the region:
  <geo2code $latitude $longitude 20000>     <!-- +/- 2 degrees -->
  <SQL "select Name from city where GeoCode between " $ret>
    $Name
  </SQL>
</A>

CAVEATS
The geo2code function was added in version 2.1.904800000 19980902.

The returned value in $ret from geo2code is platform-dependent in format and accuracy; it should not be copied across platforms. On 32-bit-long platforms it is accurate to 32 seconds (about half a mile). On 64-bit-long platforms it is accurate to 1 second (about 100 feet or less).

The between operator used here should have a regular (B-tree) index on the encoded (left-side) field, and use the parenthetical syntax. A search without parentheses (e.g. "between $x and $y" loses the special interpretation of the values and will not work correctly with geo2code values.

Note that the Texis SQL functions latlon2geocode() etc. default to east-positive longitudes, not west-positive as Vortex <geo2code> does.

SEE ALSO
<code2geo> Vortex function, latlon2geocode(), latlong2geocodearea() SQL functions