Geocode range filter format

When used with a standard attribute of type geocode, the GeocodeReferencePoint element indicates a range filter based on the distance of that geocode attribute from a given reference point.

The syntax for a geocode range filter is shown in this snippet sample from the request:
<cs:Operator xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
     xsi:type="RangeFilterOperator">
   <cs:RangeFilter AttributeName="Location">
       <cs:LowerBound>0</cs:LowerBound>
       <cs:UpperBound>20</cs:UpperBound>
       <cs:GeocodeReferencePoint Latitude="+42.365615" 
           Longitude="-71.075647"/>
   </cs:RangeFilter>
   </cs:Operator>
   ... 
</cs:Request>
The meanings of the RangeFilter elements and attributes are described in the following table:
RangeFilter Geocode Attribute Meaning
AttributeName The name of a standard attribute of type geocode. Only one standard attribute of type geocode can be specified per range filter.
LowerBound Used to specify a greater-than distance (in kilometers) from the geocode attribute to the reference point.
UpperBound Used to specify a less-than distance (in kilometers) from the geocode attribute to the reference point. Note that the range filter must contain at least one of the boundary elements.
GeocodeReferencePoint Uses the Latitude and Longitude attributes to specify a reference point for range filtering of geocode attributes.
Latitude The latitude of the location in whole and fractional degrees (positive values indicate north latitude and negative values indicate south latitude).
Longitude The longitude of the location in whole and fractional degrees (positive values indicate east longitude and negative values indicate west longitude).
Note the following about geocode range filters:
  • Distance limits (specified via the LowerBound and UpperBound elements) are exclusive. This means that you cannot use the Inclusive attribute set to true for these two elements. Because the Inclusive default is false, you can omit this attribute for geocode range filters.
  • Geocode range filters must contain at least one of the bound elements.
  • Distance limits in range filters are always expressed in kilometers.

The records are filtered by the distance from the filter key to the latitude/longitude pair.

Between geocode range filters

Use both UpperBound and LowerBound elements to indicate that the distance from the geocode attribute to the reference point is between the two bounds. The example at the beginning of this topic returns only records whose location (in the Location property) is between 0 and 20 miles from the reference point.

Less-than geocode range filters

If only the UpperBound element is used, the distance from the geocode attribute to the reference point will be less than the given amount. For example:
<Operator xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
     xsi:type="RangeFilterOperator">
   <RangeFilter AttributeName="Location">
       <UpperBound>20</UpperBound>
       <GeocodeReferencePoint Latitude="+42.365615" 
          Longitude="-71.075647"/>
   </RangeFilter>
   </Operator>

This sample query returns all records whose location is less than 20 miles from the reference point.

Greater-than geocode range filters

If only the LowerBound element is used, the distance from the geocode attribute to the reference point will be greater than the given amount. For example:
<Operator xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
     xsi:type="RangeFilterOperator">
   <RangeFilter AttributeName="Location">
       <LowerBound>20</LowerBound>
       <GeocodeReferencePoint Latitude="+42.365615" 
          Longitude="-71.075647"/>
   </RangeFilter>
</Operator>

This sample query returns all records whose location is greater than 20 miles from the reference point.