Help Center

Menu

Geospatial search

Geospatial search is the use of geographical coordinates to enable searching based upon the geographic "position" of documents. For example:

  • A news item search might enable locating news stories reported for areas close to a certain location

  • A shop search might enable locating stores and retailers located close to the searcher

A geospatial metadata coordinate is not required if you just want to plot the item onto a map in the search results (a text type metadata value will be fine as it’s just a text value you are passing to the mapping API service that will generate the map). It is only required if you wish to make use of the distance related searching (e.g. find results near this location).

Geospatial search requires that documents contain geospatial data and Funnelback is configured to use geospatial data.

Providing geospatial data to Funnelback

Documents in geospatial search collections must have a geospatial location specified through metadata in latitude and longitude format. Latitude and longitude must be represented in decimal degrees (i.e. not minutes and seconds).

<meta name="geo.position" content="-37.4500;146.0833" />

Proximity-based relevance ranking and proximity filtering are insensitive to which geodesic datum is used, but do assume that the origin given to padre and the coordinates applied to documents are expressed relative to the same datum.

If the user-supplied origin is expected to come from a GPS device, the origin will be expressed in the WGS84 system and documents should ideally be marked up according to the same system.

If a document’s geospatial position is not specified, that document’s position is assumed to be 0,0.

Funnelback requires a geospatial metadata field to follow the decimal lat/long coordinate format X-coord;Y-coord. The following may assist if you do not have coordinates available in this format:

  • Combine metadata: Use this plugin if you have the X an Y coordinate in separate metadata fields. The plugin can generate a third latlong field which should be mapped as the geospatial x/y coordinate metadata field.

  • Metadata normalizer filter: Can be used to make transformations to existing metadata fields. e.g. if you have geospatial metadata in a latlong format where the delimiter is not a semicolon, you can use this filter to update the delimiter.

To use geospatial search you must map both latitude and longitude to a single metadata class as a geospatial x/y coordinate.

Once geospatial metadata has been defined for documents within the data source, and mapped to a Funnelback metadata class, the data source should be updated or re-indexed. After re-indexing, the geospatial data is available for searching.

Detecting users' locations

Funnelback attempts to detect a user’s location automatically via their remote IP address, making this information available in the data model:

question: {
  ...
  "location": {
    "areaCode": 0,
    "city": "London",
    "countryCode": "GB",
    "countryName": "United Kingdom",
    "dmaCode": 0,
    "latitude": 51.514206,
    "longitude": -0.09309387,
    "metroCode": 0,
    "postalCode": null,
    "region": "H9"
  },
...

The latitude and longitude values are assumed to be the default origin value for any subsequent query, and are used for calculating each geocoded result’s kmFromOrigin value.

Automatically-detected locations can be overridden by manually specifying an origin, which can be performed in tandem with modern user agents' implementation of the HTML5 GeoLocation API.

See also: Geocoding Funnelback results

Query options

Once geospatial search is configured, several additional query processor options are available for use, and can be set as results page options or via CGI parameters.

origin=lat,long

specifies origin of search. Overrides the automatically-detected user location. lat and long need to be specified as decimal lat long values (e.g. 72.3,100.1)

sort=<SORT TYPE>

sort matching results by geospatial proximity to origin. prox: sort with nearest to origin first, dprox: sort with furthest from origin first.

maxdist=x

filter out results that are more than x kilometers from the origin

rmrf=<CLASS>

When a geospatial metadata class is supplied, a bounding box for all matching documents will be returned in the data model, for example -rmrf=[latLong].

Display options

After a geospatial search query has been performed, additional elements in the data model are available for display using search template syntax.

see also: Using Funnelback search results to populate a map

To display results' latitude and longitude values can be displayed as standard metadata:

<#if s.result.listMetadata["latLong"]?first??>Lat/Long: ${s.result.listMetadata["latLong"]?first!}</#if>

To display result’s distance from the origin can also be displayed using a similar approach:

<#if s.result.kmFromOrigin??>${s.result.kmFromOrigin} km away</#if>

To display the upper right coordinates of the bounding box for metadata class "latLong":

${response.resultPacket.boundingBoxes["latLong"].upperRight.latitude!}, ${response.resultPacket.boundingBoxes["latLong"].upperRight.longitude!}.

To display the lower left coordinates of the bounding box for metadata class "latLong":

${response.resultPacket.boundingBoxes["latLong"].lowerLeft.latitude!}, ${response.resultPacket.boundingBoxes["latLong"].lowerLeft.longitude!}.

See also