org.geonames

Class WebService

java.lang.Object

org.geonames.WebService

public class WebService
extends java.lang.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

Constructors

Constructor and Description
WebService()

Method Summary

Modifier and Type	Method and Description
static Address	address(double latitude, double longitude)
static int[]	astergdem(double[] latitude, double[] longitude)
static int	astergdem(double latitude, double longitude)
static ToponymSearchResult	children(int geonameId, java.lang.String language, Style style) returns the children in the administrative hierarchy of a toponym.
static ToponymSearchResult	children(int geonameId, java.lang.String language, Style style, int maxRows)
static java.lang.String	countryCode(double latitude, double longitude) The iso country code of any given point.
static java.lang.String	countryCode(double latitude, double longitude, double radius) The iso country code of any given point with radius for coastal areas.
static CountrySubdivision	countrySubdivision(double latitude, double longitude, double radius, int level, java.lang.String lang)
static java.util.List<Toponym>	findNearby(double latitude, double longitude, double radius, FeatureClass featureClass, java.lang.String[] featureCodes, java.lang.String language, int maxRows) Based on the following inforamtion: Webservice Type : REST api.geonames.org/findNearbyWikipedia?
static java.util.List<Toponym>	findNearby(double latitude, double longitude, FeatureClass featureClass, java.lang.String[] featureCodes)
static java.util.List<Toponym>	findNearbyPlaceName(double latitude, double longitude) convenience method for findNearbyPlaceName(double,double,double,int)
static java.util.List<Toponym>	findNearbyPlaceName(double latitude, double longitude, double radius, int maxRows)
static java.util.List<PostalCode>	findNearbyPostalCodes(PostalCodeSearchCriteria postalCodeSearchCriteria) returns a list of postal codes
static java.util.List<StreetSegment>	findNearbyStreets(double latitude, double longitude, double radius)
static java.util.List<StreetSegment>	findNearbyStreetsOSM(double latitude, double longitude, double radius)
static WeatherObservation	findNearByWeather(double latitude, double longitude)
static java.util.List<WikipediaArticle>	findNearbyWikipedia(double latitude, double longitude, double radius, java.lang.String language, int maxRows) Based on the following inform: Webservice Type : REST api.geonames.org/findNearbyWikipedia?
static java.util.List<WikipediaArticle>	findNearbyWikipedia(double latitude, double longitude, java.lang.String language)
static Address	findNearestAddress(double latitude, double longitude) for US only
static Intersection	findNearestIntersection(double latitude, double longitude)
static Intersection	findNearestIntersection(double latitude, double longitude, double radius)
static Address	geoCodeAddress(java.lang.String q, java.lang.String country, java.lang.String postalcode)
static Toponym	get(int geoNameId, java.lang.String language, java.lang.String style)
static int	getConnectTimeOut()
static Style	getDefaultStyle()
static java.lang.String	getGeoNamesServer()
static java.lang.String	getGeoNamesServerFailover()
static java.net.Proxy	getProxy()
static int	getReadTimeOut()
static java.lang.String	getToken()
static java.lang.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 java.util.List<Toponym>	hierarchy(int geonameId, java.lang.String language, Style style) returns the hierarchy for a geonameId
static boolean	isAndroid()
static ToponymSearchResult	neighbours(int geonameId, java.lang.String language, Style style) returns the neighbours of a toponym.
static java.lang.String	ocean(double latitude, double longitude)
static java.util.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 java.util.List<PostalCode>	postalCodeSearch(java.lang.String postalCode, java.lang.String placeName, java.lang.String countryCode) returns a list of postal codes for the given parameters.
static void	saveTags(java.lang.String[] tags, Toponym toponym, java.lang.String username, java.lang.String password)
static ToponymSearchResult	search(java.lang.String q, java.lang.String countryCode, java.lang.String name, java.lang.String[] featureCodes, int startRow) convenience method for search(ToponymSearchCriteria)
static ToponymSearchResult	search(java.lang.String q, java.lang.String countryCode, java.lang.String name, java.lang.String[] featureCodes, int startRow, java.lang.String language, Style style, java.lang.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(java.lang.String pGeoNamesServer) sets the server name for the GeoNames server to be used for the requests.
static void	setGeoNamesServerFailover(java.lang.String geoNamesServerFailover) sets the default failover server for requests in case the main server is not accessible.
static void	setProxy(java.net.Proxy proxy)
static void	setReadTimeOut(int readTimeOut)
static void	setToken(java.lang.String token) sets the token to be used to authenticate the requests.
static void	setUserName(java.lang.String userName) Sets the user name to be used for the requests.
static int[]	srtm1(double[] latitude, double[] longitude)
static int	srtm1(double latitude, double longitude)
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(java.lang.String icaoCode)
static java.util.List<WikipediaArticle>	wikipediaSearch(java.lang.String q, java.lang.String language) full text search on geolocated wikipedia articles.
static java.util.List<WikipediaArticle>	wikipediaSearchForTitle(java.lang.String title, java.lang.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 java.util.List<PostalCode> postalCodeSearch(java.lang.String postalCode,
                                                          java.lang.String placeName,
                                                          java.lang.String countryCode)
                                                   throws java.lang.Exception

returns a list of postal codes for the given parameters. This method is for convenience.

Parameters:

postalCode -

placeName -

countryCode -

Returns:

Throws:

java.lang.Exception

postalCodeSearch

public static java.util.List<PostalCode> postalCodeSearch(PostalCodeSearchCriteria postalCodeSearchCriteria)
                                                   throws java.lang.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:

java.lang.Exception

findNearbyPostalCodes

public static java.util.List<PostalCode> findNearbyPostalCodes(PostalCodeSearchCriteria postalCodeSearchCriteria)
                                                        throws java.lang.Exception

returns a list of postal codes

Parameters:

postalCodeSearchCriteria -

Returns:

Throws:

java.lang.Exception

findNearbyPlaceName

public static java.util.List<Toponym> findNearbyPlaceName(double latitude,
                                                          double longitude)
                                                   throws java.io.IOException,
                                                          java.lang.Exception

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

Parameters:

latitude -

longitude -

Returns:

Throws:

java.io.IOException

java.lang.Exception

findNearbyPlaceName

public static java.util.List<Toponym> findNearbyPlaceName(double latitude,
                                                          double longitude,
                                                          double radius,
                                                          int maxRows)
                                                   throws java.io.IOException,
                                                          java.lang.Exception

Throws:

java.io.IOException

java.lang.Exception

findNearby

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

Throws:

java.io.IOException

java.lang.Exception

findNearby

public static java.util.List<Toponym> findNearby(double latitude,
                                                 double longitude,
                                                 double radius,
                                                 FeatureClass featureClass,
                                                 java.lang.String[] featureCodes,
                                                 java.lang.String language,
                                                 int maxRows)
                                          throws java.io.IOException,
                                                 java.lang.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

Throws:

java.io.IOException

java.lang.Exception

get

public static Toponym get(int geoNameId,
                          java.lang.String language,
                          java.lang.String style)
                   throws java.io.IOException,
                          java.lang.Exception

Parameters:

geoNameId -

language - - optional

style - - optional

Returns:

the toponym for the geoNameId

Throws:

java.io.IOException

java.lang.Exception

findNearestAddress

public static Address findNearestAddress(double latitude,
                                         double longitude)
                                  throws java.io.IOException,
                                         java.lang.Exception

for US only

Parameters:

latitude -

longitude -

Returns:

Throws:

java.io.IOException

java.lang.Exception

findNearestIntersection

public static Intersection findNearestIntersection(double latitude,
                                                   double longitude)
                                            throws java.lang.Exception

Throws:

java.lang.Exception

findNearestIntersection

public static Intersection findNearestIntersection(double latitude,
                                                   double longitude,
                                                   double radius)
                                            throws java.lang.Exception

Throws:

java.lang.Exception

findNearbyStreets

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

Parameters:

latitude -

longitude -

radius -

Returns:

Throws:

java.lang.Exception

See Also:

web service documentation

findNearbyStreetsOSM

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

Throws:

java.lang.Exception

address

public static Address address(double latitude,
                              double longitude)
                       throws java.io.IOException,
                              java.lang.Exception

Throws:

java.io.IOException

java.lang.Exception

geoCodeAddress

public static Address geoCodeAddress(java.lang.String q,
                                     java.lang.String country,
                                     java.lang.String postalcode)
                              throws java.io.IOException,
                                     java.lang.Exception

Throws:

java.io.IOException

java.lang.Exception

search

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

convenience method for search(ToponymSearchCriteria)

Parameters:

q -

countryCode -

name -

featureCodes -

startRow -

Returns:

Throws:

java.lang.Exception

See Also:

search web service documentation

search

public static ToponymSearchResult search(java.lang.String q,
                                         java.lang.String countryCode,
                                         java.lang.String name,
                                         java.lang.String[] featureCodes,
                                         int startRow,
                                         java.lang.String language,
                                         Style style,
                                         java.lang.String exactName)
                                  throws java.lang.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:

java.lang.Exception

See Also:

search web service documentation

search

public static ToponymSearchResult search(ToponymSearchCriteria searchCriteria)
                                  throws java.lang.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:

java.lang.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,
                                           java.lang.String language,
                                           Style style)
                                    throws java.lang.Exception

returns the children in the administrative hierarchy of a toponym. With default maxRows.

Parameters:

geonameId -

language -

style -

Returns:

Throws:

java.lang.Exception

children

public static ToponymSearchResult children(int geonameId,
                                           java.lang.String language,
                                           Style style,
                                           int maxRows)
                                    throws java.lang.Exception

Parameters:

geonameId -

language -

style -

maxRows -

Returns:

Throws:

java.lang.Exception

neighbours

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

returns the neighbours of a toponym.

Parameters:

geonameId -

language -

style -

Returns:

Throws:

java.lang.Exception

hierarchy

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

returns the hierarchy for a geonameId

Parameters:

geonameId -

language -

style -

Returns:

Throws:

java.lang.Exception

See Also:

Hierarchy service description

saveTags

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

Throws:

java.lang.Exception

wikipediaSearch

public static java.util.List<WikipediaArticle> wikipediaSearch(java.lang.String q,
                                                               java.lang.String language)
                                                        throws java.lang.Exception

full text search on geolocated wikipedia articles.

Parameters:

q -

language -

Returns:

Throws:

java.lang.Exception

wikipediaSearchForTitle

public static java.util.List<WikipediaArticle> wikipediaSearchForTitle(java.lang.String title,
                                                                       java.lang.String language)
                                                                throws java.lang.Exception

full text search on geolocated wikipedia articles.

Parameters:

title -

language -

Returns:

Throws:

java.lang.Exception

findNearbyWikipedia

public static java.util.List<WikipediaArticle> findNearbyWikipedia(double latitude,
                                                                   double longitude,
                                                                   java.lang.String language)
                                                            throws java.lang.Exception

Throws:

java.lang.Exception

findNearbyWikipedia

public static java.util.List<WikipediaArticle> findNearbyWikipedia(double latitude,
                                                                   double longitude,
                                                                   double radius,
                                                                   java.lang.String language,
                                                                   int maxRows)
                                                            throws java.lang.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

Throws:

java.lang.Exception

gtopo30

public static int gtopo30(double latitude,
                          double longitude)
                   throws java.io.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:

java.io.IOException

GeoNamesException

srtm3

public static int srtm3(double latitude,
                        double longitude)
                 throws java.io.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:

java.io.IOException

GeoNamesException

srtm3

public static int[] srtm3(double[] latitude,
                          double[] longitude)
                   throws java.io.IOException

Throws:

java.io.IOException

srtm1

public static int srtm1(double latitude,
                        double longitude)
                 throws java.io.IOException,
                        GeoNamesException

Throws:

java.io.IOException

GeoNamesException

srtm1

public static int[] srtm1(double[] latitude,
                          double[] longitude)
                   throws java.io.IOException

Throws:

java.io.IOException

astergdem

public static int astergdem(double latitude,
                            double longitude)
                     throws java.io.IOException,
                            GeoNamesException

Throws:

java.io.IOException

GeoNamesException

astergdem

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

Throws:

java.io.IOException

countryCode

public static java.lang.String countryCode(double latitude,
                                           double longitude)
                                    throws java.io.IOException,
                                           GeoNamesException

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

Parameters:

latitude -

longitude -

Returns:

Throws:

java.io.IOException

GeoNamesException

countryCode

public static java.lang.String countryCode(double latitude,
                                           double longitude,
                                           double radius)
                                    throws java.io.IOException,
                                           GeoNamesException

The iso country code of any given point with radius for coastal areas.

Parameters:

latitude -

longitude -

radius - (optional)

Returns:

iso country code for the given latitude/longitude

Throws:

java.io.IOException

GeoNamesException

countrySubdivision

public static CountrySubdivision countrySubdivision(double latitude,
                                                    double longitude,
                                                    double radius,
                                                    int level,
                                                    java.lang.String lang)
                                             throws java.io.IOException,
                                                    java.lang.Exception

Parameters:

latitude -

longitude -

radius - (optional)

level - (optional)

lang - (optional)

Returns:

Throws:

java.io.IOException

java.lang.Exception

timezone

public static Timezone timezone(double latitude,
                                double longitude)
                         throws java.io.IOException,
                                java.lang.Exception

get the timezone for a given location

Parameters:

latitude -

longitude -

Returns:

timezone at the given location

Throws:

java.io.IOException

java.lang.Exception

ocean

public static java.lang.String ocean(double latitude,
                                     double longitude)
                              throws java.io.IOException,
                                     java.lang.Exception

Throws:

java.io.IOException

java.lang.Exception

findNearByWeather

public static WeatherObservation findNearByWeather(double latitude,
                                                   double longitude)
                                            throws java.io.IOException,
                                                   java.lang.Exception

Parameters:

latitude -

longitude -

Returns:

Throws:

java.io.IOException

java.lang.Exception

weatherIcao

public static WeatherObservation weatherIcao(java.lang.String icaoCode)
                                      throws java.io.IOException,
                                             java.lang.Exception

Throws:

java.io.IOException

java.lang.Exception

getGeoNamesServer

public static java.lang.String getGeoNamesServer()

Returns:

the geoNamesServer, default is http://api.geonames.org

getGeoNamesServerFailover

public static java.lang.String getGeoNamesServerFailover()

Returns:

the geoNamesServerFailover

setGeoNamesServer

public static void setGeoNamesServer(java.lang.String pGeoNamesServer)

sets the server name for the GeoNames server to be used for the requests. Default is api.geonames.org

Parameters:

geoNamesServer - the geonamesServer to set

setGeoNamesServerFailover

public static void setGeoNamesServerFailover(java.lang.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 java.net.Proxy getProxy()

Returns:

the proxy

setProxy

public static void setProxy(java.net.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 java.lang.String getUserName()

Returns:

the userName

setUserName

public static void setUserName(java.lang.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 java.lang.String getToken()

Returns:

the token

setToken

public static void setToken(java.lang.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