Package org.geonames

Class WebService

  • public class WebService
extends Object
    provides static methods to access the GeoNames web services.

    Note : values for some fields are only returned with sufficient Style . Accessing these fields (admin codes and admin names, elevation,population) will throw an InsufficientStyleException if the Style was not sufficient.

    Author:
    marc@geonames

    • Constructor Detail

      • WebService

        public WebService()

    • Method Detail

      • isAndroid

        public static boolean isAndroid()
        Returns:
        the isAndroid

      • postalCodeSearch

        public static List<PostalCode> postalCodeSearch​(String postalCode,
                                                String placeName,
                                                String countryCode)
                                         throws Exception
        returns a list of postal codes for the given parameters. This method is for convenience.
        Parameters:
        postalCode -
        placeName -
        countryCode -
        Returns:
        Throws:
        Exception

      • postalCodeSearch

        public static List<PostalCode> postalCodeSearch​(PostalCodeSearchCriteria postalCodeSearchCriteria)
                                         throws Exception
        returns a list of postal codes for the given search criteria matching a full text search on the GeoNames postal codes database.
        Parameters:
        postalCodeSearchCriteria -
        Returns:
        Throws:
        Exception

      • findNearby

        public static List<Toponym> findNearby​(double latitude,
                                       double longitude,
                                       double radius,
                                       FeatureClass featureClass,
                                       String[] featureCodes,
                                       String language,
                                       int maxRows)
                                throws IOException,
                                       Exception
        Based on the following inforamtion: Webservice Type : REST api.geonames.org/findNearbyWikipedia? Parameters : lang : language code (around 240 languages) (default = en) lat,lng, radius (in km), maxRows (default = 10) featureClass featureCode Example: http://api.geonames.org/findNearby?lat=47.3&lng=9
        Parameters:
        latitude -
        longitude -
        radius -
        featureClass -
        featureCodes -
        language -
        maxRows -
        Returns:
        list of wikipedia articles
        Throws:
        Exception
        IOException

      • findNearestIntersection

        public static Intersection findNearestIntersection​(double latitude,
                                                   double longitude)
                                            throws Exception
        Throws:
        Exception

      • findNearestIntersection

        public static Intersection findNearestIntersection​(double latitude,
                                                   double longitude,
                                                   double radius)
                                            throws Exception
        Throws:
        Exception

      • search

        public static ToponymSearchResult search​(ToponymSearchCriteria searchCriteria)
                                  throws Exception
        full text search on the GeoNames database.

        This service gets the number of toponyms defined by the 'maxRows' parameter. The parameter 'style' determines which fields are returned by the service.

        Parameters:
        searchCriteria -
        Returns:
        Throws:
        Exception
        See Also:
        search web service documentation 
         ToponymSearchCriteria searchCriteria = new ToponymSearchCriteria();
 searchCriteria.setQ("z&uumlrich");
 ToponymSearchResult searchResult = WebService.search(searchCriteria);
 for (Toponym toponym : searchResult.toponyms) {
 	System.out.println(toponym.getName() + " " + toponym.getCountryName());
 }

      • children

        public static ToponymSearchResult children​(int geonameId,
                                           String language,
                                           Style style)
                                    throws Exception
        returns the children in the administrative hierarchy of a toponym. With default maxRows.
        Parameters:
        geonameId -
        language -
        style -
        Returns:
        Throws:
        Exception

      • wikipediaSearchForTitle

        public static List<WikipediaArticle> wikipediaSearchForTitle​(String title,
                                                             String language)
                                                      throws Exception
        full text search on geolocated wikipedia articles.
        Parameters:
        title -
        language -
        Returns:
        Throws:
        Exception

      • findNearbyWikipedia

        public static List<WikipediaArticle> findNearbyWikipedia​(double latitude,
                                                         double longitude,
                                                         double radius,
                                                         String language,
                                                         int maxRows)
                                                  throws Exception
        Based on the following inform: Webservice Type : REST api.geonames.org/findNearbyWikipedia? Parameters : lang : language code (around 240 languages) (default = en) lat,lng, radius (in km), maxRows (default = 5) Example: http://api.geonames.org/findNearbyWikipedia?lat=47&lng=9
        Parameters:
        latitude -
        longitude -
        radius -
        language -
        maxRows -
        Returns:
        list of wikipedia articles
        Throws:
        Exception

      • gtopo30

        public static int gtopo30​(double latitude,
                          double longitude)
                   throws IOException,
                          GeoNamesException
        GTOPO30 is a global digital elevation model (DEM) with a horizontal grid spacing of 30 arc seconds (approximately 1 kilometer). GTOPO30 was derived from several raster and vector sources of topographic information.
        Parameters:
        latitude -
        longitude -
        Returns:
        a single number giving the elevation in meters according to gtopo30, ocean areas have been masked as "no data" and have been assigned a value of -9999
        Throws:
        IOException
        GeoNamesException

      • srtm3

        public static int srtm3​(double latitude,
                        double longitude)
                 throws IOException,
                        GeoNamesException
        Shuttle Radar Topography Mission (SRTM) elevation data. SRTM consisted of a specially modified radar system that flew onboard the Space Shuttle Endeavour during an 11-day mission in February of 2000. The dataset covers land areas between 60 degrees north and 56 degrees south. This web service is using SRTM3 data with data points located every 3-arc-second (approximately 90 meters) on a latitude/longitude grid.
        Parameters:
        latitude -
        longitude -
        Returns:
        elevation or -32768 if unknown
        Throws:
        IOException
        GeoNamesException

      • srtm3

        public static int[] srtm3​(double[] latitude,
                          double[] longitude)
                   throws IOException
        Throws:
        IOException

      • astergdem

        public static int[] astergdem​(double[] latitude,
                              double[] longitude)
                       throws IOException
        Throws:
        IOException

      • countryCode

        public static String countryCode​(double latitude,
                                 double longitude,
                                 double radius)
                          throws IOException,
                                 GeoNamesException
        The iso country code of any given point with radius for coastal areas.
        Parameters:
        latitude -
        longitude -
        radius -
        Returns:
        iso country code for the given latitude/longitude
        Throws:
        IOException
        GeoNamesException

      • timezone

        public static Timezone timezone​(double latitude,
                                double longitude)
                         throws IOException,
                                Exception
        get the timezone for a given location
        Parameters:
        latitude -
        longitude -
        Returns:
        timezone at the given location
        Throws:
        IOException
        Exception

      • getGeoNamesServer

        public static String getGeoNamesServer()
        Returns:
        the geoNamesServer, default is http://api.geonames.org

      • getGeoNamesServerFailover

        public static String getGeoNamesServerFailover()
        Returns:
        the geoNamesServerFailover

      • setGeoNamesServer

        public static void setGeoNamesServer​(String pGeoNamesServer)
        sets the server name for the GeoNames server to be used for the requests. Default is api.geonames.org
        Parameters:
        pGeoNamesServer - the geonamesServer to set

      • setGeoNamesServerFailover

        public static void setGeoNamesServerFailover​(String geoNamesServerFailover)
        sets the default failover server for requests in case the main server is not accessible. Default is api.geonames.org
        The failover server is only called if it is different from the main server.
        The failover server is used for commercial GeoNames web service users.
        Parameters:
        geoNamesServerFailover - the geoNamesServerFailover to set

      • getProxy

        public static Proxy getProxy()
        Returns:
        the proxy

      • setProxy

        public static void setProxy​(Proxy proxy)
        Parameters:
        proxy - the proxy to set

        If you are behind a proxy and cannot change the java system properties, you can use this method to set a proxy. You define it like this: 

                                   
                                      java.net.SocketAddress sa = new java.net.InetSocketAddress("myproxyserver", 8080);
                                      java.net.Proxy proxy = new java.net.Proxy(java.net.Proxy.Type.HTTP, sa);

      • getUserName

        public static String getUserName()
        Returns:
        the userName

      • setUserName

        public static void setUserName​(String userName)
        Sets the user name to be used for the requests. Needed to access the commercial GeoNames web services.
        Parameters:
        userName - the userName to set

      • getToken

        public static String getToken()
        Returns:
        the token

      • setToken

        public static void setToken​(String token)
        sets the token to be used to authenticate the requests. This is an optional parameter for the commercial version of the GeoNames web services.
        Parameters:
        token - the token to set

      • getDefaultStyle

        public static Style getDefaultStyle()
        Returns:
        the defaultStyle

      • setDefaultStyle

        public static void setDefaultStyle​(Style defaultStyle)
        Parameters:
        defaultStyle - the defaultStyle to set

      • getReadTimeOut

        public static int getReadTimeOut()
        Returns:
        the readTimeOut

      • setReadTimeOut

        public static void setReadTimeOut​(int readTimeOut)
        Parameters:
        readTimeOut - the readTimeOut to set

      • getConnectTimeOut

        public static int getConnectTimeOut()
        Returns:
        the connectTimeOut

      • setConnectTimeOut

        public static void setConnectTimeOut​(int connectTimeOut)
        Parameters:
        connectTimeOut - the connectTimeOut to set