WebService (OpenEstate-Tool 1.0-beta43b API)

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

Constructors
Constructor and Description

WebService()

Constructors
Constructor and Description
`WebService()`

Method Summary

All Methods Static Methods Concrete Methods
Modifier and Type	Method and Description
`static Address`	`address(double latitude, double longitude)` Find the nearest address for a given lat/lng pair.
`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 ToponymSearchResult`	`children(int geonameId, String language, Style style, int maxRows)`
`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 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
`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 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
`static List<WikipediaArticle>`	`findNearbyWikipedia(double latitude, double longitude, 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(String q, String country, String postalcode)` Returns location lat/lng and admin information for a given address.
`static Toponym`	`get(int geoNameId, String language, String style)`
`static int`	`getConnectTimeOut()`
`static Style`	`getDefaultStyle()`
`static String`	`getGeoNamesServer()`
`static String`	`getGeoNamesServerFailover()`
`static Proxy`	`getProxy()`
`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 String`	`ocean(double latitude, double longitude)`
`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)`
`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`	`setProxy(Proxy proxy)`
`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 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:: IOException; Exception

get

public static Toponym get(int geoNameId,
                          String language,
                          String style)
                   throws IOException,
                          Exception

Parameters:: geoNameId -; language - - optional; style - - optional
Returns:: the toponym for the geoNameId
Throws:: IOException; Exception

findNearestAddress

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

for US only

Parameters:: latitude -; longitude -
Returns:
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

address
```
public static Address address(double latitude,
                              double longitude)
                       throws IOException,
                              Exception
```
Find the nearest address for a given lat/lng pair. Supports several countries.
See documentation for the list of supported countries:
* @see address web service documentation

Parameters:

latitude -

longitude -

Returns:

Throws:

IOException

Exception

geoCodeAddress

public static Address geoCodeAddress(String q,
                                     String country,
                                     String postalcode)
                              throws IOException,
                                     Exception

Returns location lat/lng and admin information for a given address.

See documentation for the list of supported countries:

* @see geoCodeAddress web service documentation

Parameters:: q -; country -; postalcode -
Returns:
Throws:: IOException; 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. With default maxRows.

Parameters:: geonameId -; language -; style -
Returns:
Throws:: Exception

children

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

Parameters:: geonameId -; language -; style -; maxRows -
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 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:: 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,
                            GeoNamesException

Throws:: IOException; GeoNamesException

astergdem

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

Throws:: IOException

countryCode

public static String countryCode(double latitude,
                                 double longitude)
                          throws 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:: IOException; GeoNamesException

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

ocean

public static String ocean(double latitude,
                           double longitude)
                    throws IOException,
                           Exception

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://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

Class WebService

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

WebService

Method Detail

isAndroid

postalCodeSearch

postalCodeSearch

findNearbyPostalCodes

findNearbyPlaceName

findNearbyPlaceName

findNearby

findNearby

get

findNearestAddress

findNearestIntersection

findNearestIntersection

findNearbyStreets

findNearbyStreetsOSM

address

geoCodeAddress

search

search

search

children

children

neighbours

hierarchy

saveTags

wikipediaSearch

wikipediaSearchForTitle

findNearbyWikipedia

findNearbyWikipedia

gtopo30

srtm3

srtm3

astergdem

astergdem

countryCode

countryCode

timezone

ocean

findNearByWeather

weatherIcao

getGeoNamesServer

getGeoNamesServerFailover

setGeoNamesServer

setGeoNamesServerFailover

getProxy

setProxy

getUserName

setUserName

getToken

setToken

getDefaultStyle

setDefaultStyle

getReadTimeOut

setReadTimeOut

getConnectTimeOut

setConnectTimeOut