winterwell.jgeoplanet
Class GeoPlanet

java.lang.Object
  winterwell.jgeoplanet.GeoPlanet

public class GeoPlanet
extends java.lang.Object

Java client library for the Yahoo! GeoPlanet service as described at: http://developer.yahoo.com/geo/geoplanet/

All applications require a valid application ID. These can be obtained from: http://developer.yahoo.com/wsregapp/. The application ID is checked when you construct a GeoPlanet object. This requires network access.

Example:

 String mySecretAppId = "abc123";
 WhereOnEarth woe = new WhereOnEarth(mySecretAppId);
 Place earth = woe.get(1);
 List<Place> countries = earth.getChildren().type("Country").get();
 

Spatial entities provided by Yahoo! GeoPlanet are referenced by a 32-bit identifier: the Where On Earth ID (WOEID). WOEIDs are unique and non-repetitive, and are assigned to all entities within the system. A WOEID, once assigned, is never changed or recycled. If a WOEID is deprecated it is mapped to its successor or parent WOEID, so that requests to the service using a deprecated WOEID are served transparently.

Author:

Joe Halliwell

Field Summary

static java.lang.String	appIdUrl
static java.lang.String	defaultLanguage Default language for convenience constructors.
static java.lang.String	defaultServiceUri Default serviceURI (the Yahoo! implementation) for convenience constructors.

Constructor Summary

GeoPlanet(java.lang.String appId)
Convenience constructor for English language GeoPlanet applications.

GeoPlanet(java.lang.String appId, java.lang.String language)
Create a client for the GeoPlanet service using the specified application ID and language.

GeoPlanet(java.lang.String appId, java.lang.String language, java.lang.String serviceUri)
Create a client for the GeoPlanet service using the specified application ID, language and service URI.

Method Summary

java.lang.String	getApplicationId() Return the Yahoo! application ID used by this client.
java.lang.String	getLanguage() Returns the language used by this client such as "en-gb".
Place	getPlace(long woeId)
Place	getPlace(java.lang.String query) Returns the first Place whose name matches the query to some extent.
PlaceCollection	getPlaces(java.lang.String query) Returns a PlaceCollection of places whose names match the query to some extent.
PlaceType	getPlaceType(int placeTypeCode) Look up a PlaceType by code.
PlaceType	getPlaceType(java.lang.String placeTypeName) Look up a PlaceType by name.
java.util.Collection<PlaceType>	getPlaceTypes()
java.lang.String	getServiceUri() Returns the base URI used by the client e.g.
java.lang.String	toString()

Methods inherited from class java.lang.Object

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

Field Detail

appIdUrl

public static java.lang.String appIdUrl

defaultServiceUri

public static final java.lang.String defaultServiceUri

Default serviceURI (the Yahoo! implementation) for convenience constructors.

See Also:

Constant Field Values

defaultLanguage

public static final java.lang.String defaultLanguage

Default language for convenience constructors.

See Also:

Constant Field Values

Constructor Detail

GeoPlanet

public GeoPlanet(java.lang.String appId)
          throws GeoPlanetException

Convenience constructor for English language GeoPlanet applications.

Throws:

GeoPlanetException

See Also:

GeoPlanet(String, String, String)

GeoPlanet

public GeoPlanet(java.lang.String appId,
                 java.lang.String language)
          throws GeoPlanetException

Create a client for the GeoPlanet service using the specified application ID and language.

Parameters:

appId - your application ID

language - code for the language to use

Throws:

GeoPlanetException

See Also:

GeoPlanet(String, String, String)

GeoPlanet

public GeoPlanet(java.lang.String appId,
                 java.lang.String language,
                 java.lang.String serviceUri)
          throws GeoPlanetException

Create a client for the GeoPlanet service using the specified application ID, language and service URI. NB All constructors require network access to check the application ID and cache localised place types. The official Yahoo! service URI is http://where.yahooapis.com/v1/

Parameters:

appId - your application ID

language - code for the language to use

serviceUri - base URI for GeoPlanet requests

Throws:

GeoPlanetException

Method Detail

getApplicationId

public java.lang.String getApplicationId()

Return the Yahoo! application ID used by this client. Application IDs can be obtained from http://developer.yahoo.com/wsregapp/.

Returns:

the application ID used by this client

getLanguage

public java.lang.String getLanguage()

Returns the language used by this client such as "en-gb".

Returns:

the language used by this client

getServiceUri

public java.lang.String getServiceUri()

Returns the base URI used by the client e.g. http://where.yahooapis.com/v1

Returns:

the base URI used by this client

getPlace

public Place getPlace(long woeId)
               throws GeoPlanetException

Returns:

the place corresponding to the specified WOE ID

Throws:

PlaceNotFoundException - if the ID is invalid

GeoPlanetException - for general errors

getPlace

public Place getPlace(java.lang.String query)
               throws GeoPlanetException

Returns the first Place whose name matches the query to some extent. Roughly equivalent to calling getPlaces(String).get(0) except that it throws a PlaceNotFoundException if there were no matching places.

Throws:

PlaceNotFoundException - if there are no matches for the query

GeoPlanetException - on general errors

getPlaces

public PlaceCollection getPlaces(java.lang.String query)

Returns a PlaceCollection of places whose names match the query to some extent. The query may include an country code to adjust the ordering e.g. getPlaces("Edinburgh, UK") vs. getPlaces("Edinburgh, USA")

Returns:

a PlaceCollection of places matching the query

getPlaceTypes

public java.util.Collection<PlaceType> getPlaceTypes()

Returns:

a Collection of all known PlaceTypes

getPlaceType

public PlaceType getPlaceType(java.lang.String placeTypeName)
                       throws InvalidPlaceType

Look up a PlaceType by name.

Returns:

the PlaceType corresponding to the provided name.

Throws:

InvalidPlaceType - if the name is invalid

getPlaceType

public PlaceType getPlaceType(int placeTypeCode)
                       throws InvalidPlaceType

Look up a PlaceType by code.

Parameters:

placeTypeCode - a valid place type code

Returns:

the PlaceType corresponding to the provided code.

Throws:

InvalidPlaceType - if the code is invalid

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

See Also:

Object.toString()