org.codice.ddf.spatial.geocoding

Interface GeoEntryQueryable

All Known Implementing Classes:

GeoNamesQueryLuceneDirectoryIndex, GeoNamesQueryLuceneIndex, GeoNamesWebService

public interface GeoEntryQueryable

A GeoEntryQueryable provides methods for querying a resource containing GeoNames data.

Method Summary

Modifier and Type	Method and Description
Optional<String>	getCountryCode(String wktLocation, int radius) Retrieves the country code for the the area defined by wktLocation in a distance of up to radius from the coordinate searched.
List<NearbyLocation>	getNearestCities(String location, int radiusInKm, int maxResults) Retrieves the cities within radiusInKm kilometers of metacard, sorted by population in descending order.
List<GeoEntry>	query(String queryString, int maxResults) Retrieves the top results for the given query up to maxResults results.

Method Detail

query

List<GeoEntry> query(String queryString,
                     int maxResults)
              throws GeoEntryQueryException

Retrieves the top results for the given query up to maxResults results.

Parameters:

queryString - a String containing search terms

maxResults - the maximum number of results to return

Returns:

the top results for the query in descending order of relevance, or an empty List if no results are found

Throws:

IllegalArgumentException - if queryString is null or empty, or if maxResults is not a positive integer

GeoEntryQueryException - if an exception occurs while querying the GeoNames resource

getNearestCities

List<NearbyLocation> getNearestCities(String location,
                                      int radiusInKm,
                                      int maxResults)
                               throws ParseException,
                                      GeoEntryQueryException

Retrieves the cities within radiusInKm kilometers of metacard, sorted by population in descending order.

Each result is returned as a NearbyLocation, which describes the position of metacard relative to the city.

Parameters:

location - a WKT identifying the area to search

radiusInKm - the search radius, in kilometers

maxResults - the maximum number of results to return

Returns:

the position of metacard relative to each of the nearest cities along with the cities' names, sorted in descending order of population

Throws:

IllegalArgumentException - if metacard is null, or if radiusInKm or maxResults is not a positive integer

GeoEntryQueryException - if an exception occurs while querying the GeoNames resource

ParseException - if an exceptions occurs while parsing location

getCountryCode

Optional<String> getCountryCode(String wktLocation,
                                int radius)
                         throws GeoEntryQueryException,
                                ParseException

Retrieves the country code for the the area defined by wktLocation in a distance of up to radius from the coordinate searched.

Parameters:

wktLocation - A WKT location

radius - the radius in kilometers to search from the given wktLocation

Returns:

a country code in ISO 3166-1 alpha-2 format or null if not found (for example, a location in the ocean)

Throws:

GeoEntryQueryException

ParseException