Geo Location Filters
Geo location filters allow you to filter search results to fit within either a distance from a latitude/longitude point or within a bounding shape. The four geo location filters are:
Each of the geo location filters are only available if the app has a Map Latitude & Longitude attribute. In the examples below we're going to assume that we have a Map Latitude & Longitude attribute called "Map Point" with a layout key of "mapPoint".
You can filter by multiple attributes with each of the filters if you need to.
All of the filters are based on using latitude and longitude values.
The latitude and longitude values are expressed in decimal degrees. Positive latitudes are north of the equator, negative latitudes are south of the equator. Positive longitudes are east of prime meridian, negative longitudes are west of the prime meridian.
For example, the latitude / longitude values for Lima, Peru are 12.0433° S, 77.0283° W. The latitude value is "South" so it's value would be "-12.0433". The longitude value is "West" so it's value would be "-77.0283".
The latitude / longitude values for Paris, France are 48.8567° N, 2.3508° E. The latitude value is "North" so it's value would be "48.8567". The longitude value is "East" so it's value would be 2.3508.
Field name
The field name for the geo fields includes the attribute layout key.
The attribute layout key cannot be "location" as that is a reserved name in the search engine.
Geo Distance
The Geo Distance filter lets you filter results that are within a specific distance from a latitude / longitude point. The fields for this filter are:
- geoDistance[APP_ATTRIBUTE_LAYOUT_KEY][lat]
- geoDistance[APP_ATTRIBUTE_LAYOUT_KEY][lon]
- geoDistance[APP_ATTRIBUTE_LAYOUT_KEY][distance]
- geoDistance[APP_ATTRIBUTE_LAYOUT_KEY][town]
- geoDistance[APP_ATTRIBUTE_LAYOUT_KEY][unit]
You would replace "APP_ATTRIBUTE_LAYOUT_KEY" with the layout key of the app item attribute that you want to filter by.
All but the "unit" field are required.
geoDistance[APP_ATTRIBUTE_LAYOUT_KEY][lat]
The geoDistance[APP_ATTRIBUTE_LAYOUT_KEY][lat] field sets the latitude value to calculate the distance.
Using the latitude / longitude values for Lima, Peru (12.0433° S, 77.0283° W) filtering by our "Map Point" attribute the latitude field would be:
<input type="hidden" name="geoDistance[mapPoint][lat]" value="-12.0433">
geoDistance[APP_ATTRIBUTE_LAYOUT_KEY][lon]
The geoDistance[APP_ATTRIBUTE_LAYOUT_KEY][lon] field sets the longitude value to calculate the distance.
Using the latitude / longitude values for Lima, Peru (12.0433° S, 77.0283° W) filtering by our "Map Point" attribute the longitude field would be:
<input type="hidden" name="geoDistance[mapPoint][lon]" value="-77.0283">
geoDistance[APP_ATTRIBUTE_LAYOUT_KEY][distance]
The geoDistance[APP_ATTRIBUTE_LAYOUT_KEY][distance] field sets the distance from the latitude / longitude values that results will be limited to.
To limit results to be within 50 miles of the submitted latitude / longitude the distance field would be:
<input type="hidden" name="geoDistance[mapPoint][distance]" value="50">
geoDistance[APP_ATTRIBUTE_LAYOUT_KEY][town]
The geoDistance[APP_ATTRIBUTE_LAYOUT_KEY][town] field is only set if you have added one or more towns/cities under Settings -> Locations. This field allows you to select a town and the system will grab the stored latitude/longitude for that town and use it along with the distance field to filter results.
The field is a select menu.
If a town value is submitted in the search results then it will be used instead of submitted latitude/longitude values. If you want to use specific latitude/longitude values be sure to use Javascript to clear the town field value before submitting the search form.
geoDistance[APP_ATTRIBUTE_LAYOUT_KEY][unit]
The geoDistance[APP_ATTRIBUTE_LAYOUT_KEY][unit] field sets whether to use miles or kilometers to calculate distance in.
To specify miles use "mi".
To specify kilometers use "km".
The default is "mi" for miles.
To limit results to be within 50 kilometers of the submitted latitude / longitude the unit field would be:
<input type="hidden" name="geoDistance[mapPoint][unit]" value="km">
Geo Distance Range
The Geo Distance Range field is similar to the Geo Distance filter except that you can specify and low and high end distances to filter results by. The fields for this filter are:
geoRange[APP_ATTRIBUTE_LAYOUT_KEY][lat]
geoRange[APP_ATTRIBUTE_LAYOUT_KEY][lat]
geoRange[APP_ATTRIBUTE_LAYOUT_KEY][from]
geoRange[APP_ATTRIBUTE_LAYOUT_KEY][to]
geoRange[APP_ATTRIBUTE_LAYOUT_KEY][unit]
You would replace "APP_ATTRIBUTE_LAYOUT_KEY" with the layout key of the app item attribute that you want to filter by.
All but the "unit" field are required.
geoRange[APP_ATTRIBUTE_LAYOUT_KEY][lat]
The geoRange[APP_ATTRIBUTE_LAYOUT_KEY][lat] field sets the latitude value to calculate the distance.
Using the latitude / longitude values for Lima, Peru (12.0433° S, 77.0283° W) filtering by our "Map Point" attribute the latitude field would be:
<input type="hidden" name="geoRange[mapPoint][lat]" value="-12.0433">
geoRange[APP_ATTRIBUTE_LAYOUT_KEY][lon]
The geoRange[APP_ATTRIBUTE_LAYOUT_KEY][lon] field sets the longitude value to calculate the distance.
Using the latitude / longitude values for Lima, Peru (12.0433° S, 77.0283° W) filtering by our "Map Point" attribute the longitude field would be:
<input type="hidden" name="geoRange[mapPoint][lon]" value="-77.0283">
geoRange[APP_ATTRIBUTE_LAYOUT_KEY][from]
The geoRange[APP_ATTRIBUTE_LAYOUT_KEY][from] field sets the bottom distance range from the latitude / longitude values that results will be limited to.
To limit results to be within 50 miles to 100 miles of the submitted latitude / longitude the from field would be:
<input type="hidden" name="geoRange[mapPoint][from]" value="50">
geoRange[APP_ATTRIBUTE_LAYOUT_KEY][to]
The geoRange[APP_ATTRIBUTE_LAYOUT_KEY][to] field sets the top distance range from the latitude / longitude values that results will be limited to.
To limit results to be within 50 miles to 100 miles of the submitted latitude / longitude the to field would be:
<input type="hidden" name="geoRange[mapPoint][to]" value="100">
geoRange[APP_ATTRIBUTE_LAYOUT_KEY][unit]
The geoRange[APP_ATTRIBUTE_LAYOUT_KEY][unit] field sets whether to use miles or kilometers to calculate distance in.
To specify miles use "mi".
To specify kilometers use "km".
The default is "mi" for miles.
To limit results to be within 50 to 100 kilometers of the submitted latitude / longitude the unit field would be:
<input type="hidden" name="geoRange[mapPoint][unit]" value="km">
Geo Bounding Box
The Geo Bounding Box filter lets you filter search results that fit within a rectangular geo space.
The fields for this filter are:
geoBox[APP_ATTRIBUTE_LAYOUT_KEY][top_left][lat]
geoBox[APP_ATTRIBUTE_LAYOUT_KEY][top_left][lon]
geoBox[APP_ATTRIBUTE_LAYOUT_KEY][bottom_right][lat]
geoBox[APP_ATTRIBUTE_LAYOUT_KEY][bottom_right][lon]
You would replace "APP_ATTRIBUTE_LAYOUT_KEY" with the layout key of the app item attribute that you want to filter by.
To use this filter you set the top left latitude / longitude values and the bottom right latitude / longitude values to mark the boundaries of the bounding box.
geoBox[APP_ATTRIBUTE_LAYOUT_KEY][top_left][lat] is the latitude value for the top left of the bounding box.
geoBox[APP_ATTRIBUTE_LAYOUT_KEY][top_left][lon] is the longitude value for the top left of the bounding box.
geoBox[APP_ATTRIBUTE_LAYOUT_KEY][bottom_right][lat] is the latitude value for the bottom right of the bounding box.
geoBox[APP_ATTRIBUTE_LAYOUT_KEY][bottom_right][lon] is the longitude value for the bottom right of the bounding box.
Below is a full example.
<input type="text" name="geoBox[mapPoint][top_left][lat]" value="40.73">
<input type="text" name="geoBox[mapPoint][top_left][lon]" value="-74.1">
<input type="text" name="geoBox[mapPoint][bottom_right][lat]" value="40.01">
<input type="text" name="geoBox[mapPoint][bottom_right][lon]" value="-71.12">
Geo Polygon
The Geo Polygon filter lets you filter search results that fit within a polygon geo space.
The fields for this filter follow this naming pattern:
geoPolygon[APP_ATTRIBUTE_LAYOUT_KEY][0][lat]
geoPolygon[APP_ATTRIBUTE_LAYOUT_KEY][0][lon]
geoPolygon[APP_ATTRIBUTE_LAYOUT_KEY][1][lat]
geoPolygon[APP_ATTRIBUTE_LAYOUT_KEY][1][lon]
geoPolygon[APP_ATTRIBUTE_LAYOUT_KEY][2][lat]
geoPolygon[APP_ATTRIBUTE_LAYOUT_KEY][2][lon]
You would replace "APP_ATTRIBUTE_LAYOUT_KEY" with the layout key of the app item attribute that you want to filter by.
As you can see there is a pair of latitude (the 'lat' field) and longitude (the 'lon' field) values. Each pair represents one of the outer points of the polygon. They are associated together by having the same numeric value in the name between the layout key and 'lat' or 'lon' respectively.
Below is a full example:
<input type="text" name="geoPolygon[mapPoint][0][lat]" value="40">
<input type="text" name="geoPolygon[mapPoint][0][lon]" value="-70">
<input type="text" name="geoPolygon[mapPoint][1][lat]" value="30">
<input type="text" name="geoPolygon[mapPoint][1][lon]" value="-80">
<input type="text" name="geoPolygon[mapPoint][2][lat]" value="20">
<input type="text" name="geoPolygon[mapPoint][2][lon]" value="-90">
This example has three geo points to make up the polygon. You can, however, have more than three if necessary, but you wouldn't ever have less than three geo points.