Package org.codice.ddf.spatial.geocoding

Interface GeoEntryQueryable

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

  • Method Summary

    Modifier and Type
    Method
    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<Suggestion>
    getSuggestedNames(String queryString, int maxResults)
    Retrieves auto-complete suggestions based on a partial or full word queryString
    List<GeoEntry>
    query(String queryString, int maxResults)
    Retrieves the top results for the given query up to maxResults results.
    GeoEntry
    queryById(String id)
    Retrieves the GeoEntry corresponding to the supplied identifier.

  • Method Details

    • 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

    • queryById

      GeoEntry queryById(String id) throws GeoEntryQueryException
      Retrieves the GeoEntry corresponding to the supplied identifier. Suggestion ids may be passed to this method to retrieve the GeoEntry for a specific suggestion.
      Parameters:
      id - String identifier used to retrieve a specific GeoEntry
      Returns:
      GeoEntry matching the identifier supplied or null if not found
      Throws:
      IllegalArgumentException - if id is null or empty
      GeoEntryQueryException - if an exception occurs while querying the GeoNames resource

    • getSuggestedNames

      List<Suggestion> getSuggestedNames(String queryString, int maxResults) throws GeoEntryQueryException
      Retrieves auto-complete suggestions based on a partial or full word queryString
      Parameters:
      queryString - a partial or full search phrase
      maxResults - the maximum number of results to return
      Returns:
      List of Suggestion corresponding to queryString
      Throws:
      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-3 format or null if not found (for example, a location in the ocean)
      Throws:
      GeoEntryQueryException
      ParseException