Geospatial sorting

You implement query-time geospatial sorting by using a geocode attribute as a sort key.

Geocode attributes represent latitude and longitude pairs to Endeca records. Result sets that have geocode attribute assignments can be sorted by the distance of the values of the geocode assignment values to a given geocode reference point.

For example, if the records of a particular data set represent individual books that a large vendor has for sale at a variety of locations, each book could be tagged with a geocode attribute (for example, named Location) that holds the store location information for that particular book. Users could then filter result sets to see only books that are located within a given distance, and then sort those books so that the closest books display first.

A geocode attribute can be configured as a multi-assign attribute, which means that an Endeca record may have more than one geocode location. In this case, the Dgraph compares the query’s geocode reference point to all geocode values on the record and returns the record with the closest distance to the reference point.

Note: This feature is supported only if you use a Conversation Web Service request. It is not supported in Studio's user interface.

Specifying the geocode reference point in RecordListConfig

The Sort type in a RecordListConfig configuration lets you specify a geocode reference point, with this format:

<Sort Key="?" Direction="?">
   <GeocodeReferencePoint latitude="?" longitude="?"/>
</Sort>

Key is the name of the geocode attribute on which to sort. Direction (which is optional) is either Ascending for an ascending order (which is the default) or Descending for a descending order.

In the GeocodeReferencePoint element, you specify the geocode coordinates as doubles:

latitude is the latitude of the location in whole and fractional degrees. Valid values are from a minimum of -90.0 to a maximum of 90.0 (inclusive). Positive values indicate north latitudes and negative values indicate south latitudes.
longitude is the longitude of the location in whole and fractional degrees. Valid values are from a minimum of -180.0 to a maximum of 180.0 (inclusive). Positive values indicate east longitudes and negative values indicate west longitudes.

Geocode sort example

The following request uses the Location geocode attribute as the sort key.

<Request>
   <Language>en</Language>
   <State>
      <Name>GeoQuery</Name>
      <SelectionFilter Id="SelFlt">
         <filterString>WineID > 10</filterString>
      </SelectionFilter>
   </State>
   <RecordListConfig Id="Results" MaxPages="20">
      <StateName>GeoQuery</StateName>
      <RecordsPerPage>20</RecordsPerPage>
      <Sort Key="Location" Direction="Ascending">
         <GeocodeReferencePoint latitude="42.365615" longitude="-71.075647"/>
      </Sort>
   </RecordListConfig>
</Request>

The records are returned in a RecordList type.

Computed distances in the response

In a geospatial sort, the Dgraph Engine creates a pair of computed dynamic properties for each record returned, as illustrated by this abbreviated example for one record:

<cs:RecordListEntry>
   <cs:Record>
      <cs:attribute name="Flavors" type="mdex:string">Cherry</cs:attribute>
      ...
      <cs:attribute name="WineType" type="mdex:string">Merlot</cs:attribute>
   </cs:Record>
   <cs:ComputedProperties>
      <cs:GeocodeDistance queryString="Location(42.3656,-71.0756)" units="kilometers">296.17527882382</cs:GeocodeDistance>
      <cs:GeocodeDistance queryString="Location(42.3656,-71.0756)" units="miles">184.034729178036</cs:GeocodeDistance>
   </cs:ComputedProperties>
</cs:RecordListEntry>

The GeocodeDistance dynamic properties show the distance (in kilometers and miles, respectively) between the record's geocode address and the geocode reference point specified in the sort key. A record that does not have a geocode attribute assignment will have "NaN" (Not-a-Number) as the geocode distance.

These GeocodeDistance properties are intended for display purposes and are not persistent (that is, they are not added to the records).