org.agorava.twitter

Interface TwitterGeoService

public interface TwitterGeoService

Interface defining the Twitter operations for working with locations.

Author:

Craig Walls, Antoine Sabot-Durand

Method Summary

Methods

Modifier and Type	Method and Description
Place	createPlace(PlacePrototype placePrototype) Creates a new place.
SimilarPlaces	findSimilarPlaces(double latitude, double longitude, String name) Finds places similar to a place described in the parameters.
SimilarPlaces	findSimilarPlaces(double latitude, double longitude, String name, String streetAddress, String containedWithin) Finds places similar to a place described in the parameters.
Place	getPlace(String id) Retrieves information about a place
List<Place>	reverseGeoCode(double latitude, double longitude) Retrieves up to 20 places matching the given location.
List<Place>	reverseGeoCode(double latitude, double longitude, PlaceType granularity, String accuracy) Retrieves up to 20 places matching the given location and criteria
List<Place>	search(double latitude, double longitude) Searches for up to 20 places matching the given location.
List<Place>	search(double latitude, double longitude, PlaceType granularity, String accuracy, String query) Searches for up to 20 places matching the given location and criteria

Method Detail

getPlace

Place getPlace(String id)

Retrieves information about a place

Parameters:

id - the place ID

Returns:

a Place

Throws:

ApiException - if there is an error while communicating with Twitter.

reverseGeoCode

List<Place> reverseGeoCode(double latitude,
                         double longitude)

Retrieves up to 20 places matching the given location.

Parameters:

latitude - the latitude

longitude - the longitude

Returns:

a list of Places that the point is within

Throws:

ApiException - if there is an error while communicating with Twitter.

reverseGeoCode

List<Place> reverseGeoCode(double latitude,
                         double longitude,
                         PlaceType granularity,
                         String accuracy)

Retrieves up to 20 places matching the given location and criteria

Parameters:

latitude - the latitude

longitude - the longitude

granularity - the minimal granularity of the places to return. If null, the default granularity (neighborhood) is assumed.

accuracy - a radius of accuracy around the given point. If given a number, the value is assumed to be in meters. The number may be qualified with "ft" to indicate feet. If null, the default accuracy (0m) is assumed.

Returns:

a list of Places that the point is within

Throws:

ApiException - if there is an error while communicating with Twitter.

search

List<Place> search(double latitude,
                 double longitude)

Searches for up to 20 places matching the given location.

Parameters:

latitude - the latitude

longitude - the longitude

Returns:

a list of Places that the point is within

Throws:

ApiException - if there is an error while communicating with Twitter.

search

List<Place> search(double latitude,
                 double longitude,
                 PlaceType granularity,
                 String accuracy,
                 String query)

Searches for up to 20 places matching the given location and criteria

Parameters:

latitude - the latitude

longitude - the longitude

granularity - the minimal granularity of the places to return. If null, the default granularity (neighborhood) is assumed.

accuracy - a radius of accuracy around the given point. If given a number, the value is assumed to be in meters. The number may be qualified with "ft" to indicate feet. If null, the default accuracy (0m) is assumed.

query - a free form text value to help find places by name. If null, no query will be applied to the search.

Returns:

a list of Places that the point is within

Throws:

ApiException - if there is an error while communicating with Twitter.

findSimilarPlaces

SimilarPlaces findSimilarPlaces(double latitude,
                              double longitude,
                              String name)

Finds places similar to a place described in the parameters. Returns a list of places along with a token that is required for creating a new place. This method must be called before calling createPlace().

Parameters:

latitude - the latitude

longitude - the longitude

name - the name that the place is known as

Returns:

a SimilarPlaces collection, including a token that can be used to create a new place.

Throws:

ApiException - if there is an error while communicating with Twitter.

findSimilarPlaces

SimilarPlaces findSimilarPlaces(double latitude,
                              double longitude,
                              String name,
                              String streetAddress,
                              String containedWithin)

Finds places similar to a place described in the parameters. Returns a list of places along with a token that is required for creating a new place. This method must be called before calling createPlace().

Parameters:

latitude - the latitude

longitude - the longitude

name - the name that the place is known as

streetAddress - the place's street address. May be null.

containedWithin - the ID of the place that the place is contained within

Returns:

a SimilarPlaces collection, including a token that can be used to create a new place.

Throws:

ApiException - if there is an error while communicating with Twitter.

createPlace

Place createPlace(PlacePrototype placePrototype)

Creates a new place.

Parameters:

placePrototype - the place prototype returned in a SimilarPlaces from a call to findSimilarPlaces()

Returns:

a Place object with the newly created place data

Throws:

ApiException - if there is an error while communicating with Twitter.