twitter4j.api
Interface GeoMethods

All Known Subinterfaces:

Twitter

All Known Implementing Classes:

TwitterImpl

public interface GeoMethods

Since:

Twitter4J 2.1.1

Author:

Yusuke Yamamoto - yusuke at mac.com

Method Summary

Place	createPlace(java.lang.String name, java.lang.String containedWithin, java.lang.String token, GeoLocation location, java.lang.String streetAddress) Creates a new place at the given latitude and longitude.
Place	getGeoDetails(java.lang.String id) Find out more details of a place that was returned from the reverseGeoCode(twitter4j.GeoQuery) method.
SimilarPlaces	getSimilarPlaces(GeoLocation location, java.lang.String name, java.lang.String containedWithin, java.lang.String streetAddress) Locates places near the given coordinates which are similar in name.
ResponseList<Place>	reverseGeoCode(GeoQuery query) Search for places (cities and neighborhoods) that can be attached to a statuses/update.
ResponseList<Place>	searchPlaces(GeoQuery query) Search for places that can be attached to a statuses/update.

Method Detail

searchPlaces

ResponseList<Place> searchPlaces(GeoQuery query)
                                 throws TwitterException

Search for places that can be attached to a statuses/update. Given a latitude and a longitude pair, an IP address, or a name, this request will return a list of all the valid places that can be used as the place_id when updating a status.
Conceptually, a query can be made from the user's location, retrieve a list of places, have the user validate the location he or she is at, and then send the ID of this location with a call to statuses/update.
This is the recommended method to use find places that can be attached to statuses/update. Unlike geo/reverse_geocode which provides raw data access, this endpoint can potentially re-order places with regards to the user who is authenticated. This approach is also preferred for interactive place matching with the user.
This method calls http://api.twitter.com/1/geo/search.json

Parameters:

query - search query

Returns:

places (cities and neighborhoods) that can be attached to a statuses/update

Throws:

TwitterException - when Twitter service or network is unavailable

Since:

Twitter4J 2.1.7

See Also:

GET geo/search | dev.twitter.com

getSimilarPlaces

SimilarPlaces getSimilarPlaces(GeoLocation location,
                               java.lang.String name,
                               java.lang.String containedWithin,
                               java.lang.String streetAddress)
                               throws TwitterException

Locates places near the given coordinates which are similar in name.
Conceptually you would use this method to get a list of known places to choose from first. Then, if the desired place doesn't exist, make a request to post/geo/place to create a new one.
The token contained in the response is the token needed to be able to create a new place.
This method calls http://api.twitter.com/1/geo/similar_places.json

Parameters:

location - The latitude and longitude to search around.

name - The name a place is known as.

containedWithin - optional: the place_id which you would like to restrict the search results to. Setting this value means only places within the given place_id will be found.

streetAddress - optional: This parameter searches for places which have this given street address. There are other well-known, and application specific attributes available. Custom attributes are also permitted. Learn more about Place Attributes.

Returns:

places (cities and neighborhoods) that can be attached to a statuses/update

Throws:

TwitterException - when Twitter service or network is unavailable

Since:

Twitter4J 2.1.7

reverseGeoCode

ResponseList<Place> reverseGeoCode(GeoQuery query)
                                   throws TwitterException

Search for places (cities and neighborhoods) that can be attached to a statuses/update. Given a latitude and a longitude, return a list of all the valid places that can be used as a place_id when updating a status. Conceptually, a query can be made from the user's location, retrieve a list of places, have the user validate the location he or she is at, and then send the ID of this location up with a call to statuses/update.
There are multiple granularities of places that can be returned -- "neighborhoods", "cities", etc. At this time, only United States data is available through this method.
This API call is meant to be an informative call and will deliver generalized results about geography.
This method calls http://api.twitter.com/1/geo/reverse_geocode.json

Parameters:

query - search query

Returns:

places (cities and neighborhoods) that can be attached to a statuses/update

Throws:

TwitterException - when Twitter service or network is unavailable

Since:

Twitter4J 2.1.1

See Also:

GET geo/reverse_geocode | dev.twitter.com

getGeoDetails

Place getGeoDetails(java.lang.String id)
                    throws TwitterException

Find out more details of a place that was returned from the reverseGeoCode(twitter4j.GeoQuery) method.
This method calls http://api.twitter.com/1/geo/id/:id.json

Parameters:

id - The ID of the location to query about.

Returns:

details of the specified place

Throws:

TwitterException - when Twitter service or network is unavailable

Since:

Twitter4J 2.1.1

See Also:

GET geo/id/:place_id | dev.twitter.com

createPlace

Place createPlace(java.lang.String name,
                  java.lang.String containedWithin,
                  java.lang.String token,
                  GeoLocation location,
                  java.lang.String streetAddress)
                  throws TwitterException

Creates a new place at the given latitude and longitude.
This method calls http://api.twitter.com/1/geo/place.json

Parameters:

name - The name a place is known as.

containedWithin - The place_id within which the new place can be found. Try and be as close as possible with the containing place. For example, for a room in a building, set the contained_within as the building place_id.

token - The token found in the response from geo/similar_places.

location - The latitude and longitude the place is located at.

streetAddress - optional: This parameter searches for places which have this given street address. There are other well-known, and application specific attributes available. Custom attributes are also permitted. Learn more about Place Attributes.

Returns:

the created place

Throws:

TwitterException - when Twitter service or network is unavailable

Since:

Twitter4J 2.1.7

See Also:

POST geo/place | dev.twitter.com