org.geonames
Class WebService

java.lang.Object
  org.geonames.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 Summary

WebService()

Method Summary

static int[]	astergdem(double[] latitude, double[] longitude)
static int	astergdem(double latitude, double longitude)
static ToponymSearchResult	children(int geonameId, String language, Style style) returns the children in the administrative hierarchy of a toponym.
static String	countryCode(double latitude, double longitude) The iso country code of any given point.
static String	countryCode(double latitude, double longitude, double radius) The iso country code of any given point with radius for coastal areas.
static List<Toponym>	findNearby(double latitude, double longitude, double radius, FeatureClass featureClass, String[] featureCodes, String language, int maxRows) Based on the following inforamtion: Webservice Type : REST ws.geonames.org/findNearbyWikipedia?
static List<Toponym>	findNearby(double latitude, double longitude, FeatureClass featureClass, String[] featureCodes)
static List<Toponym>	findNearbyPlaceName(double latitude, double longitude) convenience method for findNearbyPlaceName(double,double,double,int)
static List<Toponym>	findNearbyPlaceName(double latitude, double longitude, double radius, int maxRows)
static List<PostalCode>	findNearbyPostalCodes(PostalCodeSearchCriteria postalCodeSearchCriteria) returns a list of postal codes
static List<StreetSegment>	findNearbyStreets(double latitude, double longitude, double radius)
static List<StreetSegment>	findNearbyStreetsOSM(double latitude, double longitude, double radius)
static WeatherObservation	findNearByWeather(double latitude, double longitude)
static List<WikipediaArticle>	findNearbyWikipedia(double latitude, double longitude, double radius, String language, int maxRows) Based on the following inform: Webservice Type : REST ws.geonames.org/findNearbyWikipedia?
static List<WikipediaArticle>	findNearbyWikipedia(double latitude, double longitude, String language)
static Address	findNearestAddress(double latitude, double longitude)
static Intersection	findNearestIntersection(double latitude, double longitude)
static Intersection	findNearestIntersection(double latitude, double longitude, double radius)
static int	getConnectTimeOut()
static Style	getDefaultStyle()
static String	getGeoNamesServer()
static String	getGeoNamesServerFailover()
static int	getReadTimeOut()
static String	getToken()
static String	getUserName()
static int	gtopo30(double latitude, double longitude) GTOPO30 is a global digital elevation model (DEM) with a horizontal grid spacing of 30 arc seconds (approximately 1 kilometer).
static List<Toponym>	hierarchy(int geonameId, String language, Style style) returns the hierarchy for a geonameId
static boolean	isAndroid()
static ToponymSearchResult	neighbours(int geonameId, String language, Style style) returns the neighbours of a toponym.
static List<PostalCode>	postalCodeSearch(PostalCodeSearchCriteria postalCodeSearchCriteria) returns a list of postal codes for the given search criteria matching a full text search on the GeoNames postal codes database.
static List<PostalCode>	postalCodeSearch(String postalCode, String placeName, String countryCode) returns a list of postal codes for the given parameters.
static void	saveTags(String[] tags, Toponym toponym, String username, String password)
static ToponymSearchResult	search(String q, String countryCode, String name, String[] featureCodes, int startRow) convenience method for search(ToponymSearchCriteria)
static ToponymSearchResult	search(String q, String countryCode, String name, String[] featureCodes, int startRow, String language, Style style, String exactName) convenience method for search(ToponymSearchCriteria) The string fields will be transparently utf8 encoded within the call.
static ToponymSearchResult	search(ToponymSearchCriteria searchCriteria) full text search on the GeoNames database.
static void	setConnectTimeOut(int connectTimeOut)
static void	setDefaultStyle(Style defaultStyle)
static void	setGeoNamesServer(String pGeoNamesServer) sets the server name for the GeoNames server to be used for the requests.
static void	setGeoNamesServerFailover(String geoNamesServerFailover) sets the default failover server for requests in case the main server is not accessible.
static void	setReadTimeOut(int readTimeOut)
static void	setToken(String token) sets the token to be used to authenticate the requests.
static void	setUserName(String userName) Sets the user name to be used for the requests.
static int[]	srtm3(double[] latitude, double[] longitude)
static int	srtm3(double latitude, double longitude) Shuttle Radar Topography Mission (SRTM) elevation data.
static Timezone	timezone(double latitude, double longitude) get the timezone for a given location
static WeatherObservation	weatherIcao(String icaoCode)
static List<WikipediaArticle>	wikipediaSearch(String q, String language) full text search on geolocated wikipedia articles.
static List<WikipediaArticle>	wikipediaSearchForTitle(String title, String language) full text search on geolocated wikipedia articles.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

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

findNearbyPostalCodes

public static List<PostalCode> findNearbyPostalCodes(PostalCodeSearchCriteria postalCodeSearchCriteria)
                                              throws Exception

returns a list of postal codes

Parameters:

postalCodeSearchCriteria -

Returns:

Throws:

Exception

findNearbyPlaceName

public static List<Toponym> findNearbyPlaceName(double latitude,
                                                double longitude)
                                         throws IOException,
                                                Exception

convenience method for findNearbyPlaceName(double,double,double,int)

Parameters:

latitude -

longitude -

Returns:

Throws:

IOException

Exception

findNearbyPlaceName

public static List<Toponym> findNearbyPlaceName(double latitude,
                                                double longitude,
                                                double radius,
                                                int maxRows)
                                         throws IOException,
                                                Exception

Throws:

IOException

Exception

findNearby

public static List<Toponym> findNearby(double latitude,
                                       double longitude,
                                       FeatureClass featureClass,
                                       String[] featureCodes)
                                throws IOException,
                                       Exception

Throws:

IOException

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 ws.geonames.org/findNearbyWikipedia? Parameters : lang : language code (around 240 languages) (default = en) lat,lng, radius (in km), maxRows (default = 10) featureClass featureCode Example: http://ws.geonames.org/findNearby?lat=47.3&lng=9

Throws:

IOException

Exception

findNearestAddress

public static Address findNearestAddress(double latitude,
                                         double longitude)
                                  throws IOException,
                                         Exception

Throws:

IOException

Exception

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

findNearbyStreets

public static List<StreetSegment> findNearbyStreets(double latitude,
                                                    double longitude,
                                                    double radius)
                                             throws Exception

Parameters:

latitude -

longitude -

radius -

Returns:

Throws:

Exception

See Also:

web service documentation

findNearbyStreetsOSM

public static List<StreetSegment> findNearbyStreetsOSM(double latitude,
                                                       double longitude,
                                                       double radius)
                                                throws Exception

Throws:

Exception

search

public static ToponymSearchResult search(String q,
                                         String countryCode,
                                         String name,
                                         String[] featureCodes,
                                         int startRow)
                                  throws Exception

convenience method for search(ToponymSearchCriteria)

Parameters:

q -

countryCode -

name -

featureCodes -

startRow -

Returns:

Throws:

Exception

See Also:

search web service documentation

search

public static ToponymSearchResult search(String q,
                                         String countryCode,
                                         String name,
                                         String[] featureCodes,
                                         int startRow,
                                         String language,
                                         Style style,
                                         String exactName)
                                  throws Exception

convenience method for search(ToponymSearchCriteria) The string fields will be transparently utf8 encoded within the call.

Parameters:

q - search over all fields

countryCode -

name - search over name only

featureCodes -

startRow -

language -

style -

exactName -

Returns:

Throws:

Exception

See Also:

search web service documentation

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.

Parameters:

geonameId -

language -

style -

Returns:

Throws:

Exception

neighbours

public static ToponymSearchResult neighbours(int geonameId,
                                             String language,
                                             Style style)
                                      throws Exception

returns the neighbours of a toponym.

Parameters:

geonameId -

language -

style -

Returns:

Throws:

Exception

hierarchy

public static List<Toponym> hierarchy(int geonameId,
                                      String language,
                                      Style style)
                               throws Exception

returns the hierarchy for a geonameId

Parameters:

geonameId -

language -

style -

Returns:

Throws:

Exception

See Also:

Hierarchy service description

saveTags

public static void saveTags(String[] tags,
                            Toponym toponym,
                            String username,
                            String password)
                     throws Exception

Throws:

Exception

wikipediaSearch

public static List<WikipediaArticle> wikipediaSearch(String q,
                                                     String language)
                                              throws Exception

full text search on geolocated wikipedia articles.

Parameters:

q -

language -

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,
                                                         String language)
                                                  throws Exception

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 ws.geonames.org/findNearbyWikipedia? Parameters : lang : language code (around 240 languages) (default = en) lat,lng, radius (in km), maxRows (default = 5) Example: http://ws.geonames.org/findNearbyWikipedia?lat=47&lng=9

Throws:

Exception

gtopo30

public static int gtopo30(double latitude,
                          double longitude)
                   throws IOException

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

srtm3

public static int srtm3(double latitude,
                        double longitude)
                 throws IOException

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

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

astergdem

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

Throws:

IOException

countryCode

public static String countryCode(double latitude,
                                 double longitude)
                          throws IOException

The iso country code of any given point. It is calling countryCode(double, double, double) with radius=0.0

Parameters:

latitude -

longitude -

Returns:

Throws:

IOException

countryCode

public static String countryCode(double latitude,
                                 double longitude,
                                 double radius)
                          throws IOException

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

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

findNearByWeather

public static WeatherObservation findNearByWeather(double latitude,
                                                   double longitude)
                                            throws IOException,
                                                   Exception

Parameters:

latitude -

longitude -

Returns:

Throws:

IOException

Exception

weatherIcao

public static WeatherObservation weatherIcao(String icaoCode)
                                      throws IOException,
                                             Exception

Throws:

IOException

Exception

getGeoNamesServer

public static String getGeoNamesServer()

Returns:

the geoNamesServer, default is http://ws.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 ws.geonames.org

Parameters:

geoNamesServer - 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 ws.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

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