Module: Twitter::Client::PlacesAndGeo

Included in:
Twitter::Client
Defined in:
lib/twitter/client/places_and_geo.rb

Overview

Defines methods related to geography

See Also:

Instance Method Summary collapse

Instance Method Details

#place(place_id, options = {}) ⇒ Twitter::Place

Returns all the information about a known place

Examples:

Return all the information about Twitter HQ

Twitter.place("247f43d441defc03")

Parameters:

  • place_id (String) —

    A place in the world. These IDs can be retrieved from Geo#reverse_geocode.

  • options (Hash) (defaults to: {}) —

    A customizable set of options.

Returns:

See Also:

Rate Limited?:

  • Yes

Requires Authentication?:

  • No



86
87
88
89
 
# File 'lib/twitter/client/places_and_geo.rb', line 86

def place(place_id, options={})
  place = get("/1/geo/id/#{place_id}.json", options)
  Twitter::Place.new(place)
end

#place_create(options = {}) ⇒ Twitter::Place

Creates a new place at the given latitude and longitude

Examples:

Create a new place

Twitter.place_create(:name => "@sferik's Apartment", :token => "22ff5b1f7159032cf69218c4d8bb78bc", :contained_within => "41bcb736f84a799e", :lat => "37.783699", :long => "-122.393581")

Parameters:

  • options (Hash) (defaults to: {}) —

    A customizable set of options.

Options Hash (options):

  • :name (String) —

    The name a place is known as.

  • :contained_within (String) —

    This is 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.

  • :token (String) —

    The token found in the response from Geo#places_similar.

  • :lat (Float) —

    The latitude to search around. This option will be ignored unless it is inside the range -90.0 to +90.0 (North is positive) inclusive. It will also be ignored if there isn't a corresponding :long option.

  • :long (Float) —

    The longitude to search around. The valid range for longitude is -180.0 to +180.0 (East is positive) inclusive. This option will be ignored if outside that range, if it is not a number, if geo_enabled is disabled, or if there not a corresponding :lat option.

  • :"attribute:street_address" (String) —

    This option searches for places which have this given street address. There are other well-known and application-specific attributes available. Custom attributes are also permitted.

Returns:

See Also:

Rate Limited?:

  • Yes

Requires Authentication?:

  • No



106
107
108
109
 
# File 'lib/twitter/client/places_and_geo.rb', line 106

def place_create(options={})
  place = post("/1/geo/place.json", options)
  Twitter::Place.new(place)
end

#places_nearby(options = {}) ⇒ Array<Twitter::Place> Also known as: geo_search

Search for places that can be attached to a Tweets#update

Examples:

Return an array of places near the IP address 74.125.19.104

Twitter.places_nearby(:ip => "74.125.19.104")

Parameters:

  • options (Hash) (defaults to: {}) —

    A customizable set of options.

Options Hash (options):

  • :lat (Float) —

    The latitude to search around. This option will be ignored unless it is inside the range -90.0 to +90.0 (North is positive) inclusive. It will also be ignored if there isn't a corresponding :long option.

  • :long (Float) —

    The longitude to search around. The valid range for longitude is -180.0 to +180.0 (East is positive) inclusive. This option will be ignored if outside that range, if it is not a number, if geo_enabled is disabled, or if there not a corresponding :lat option.

  • :query (String) —

    Free-form text to match against while executing a geo-based query, best suited for finding nearby locations by name.

  • :ip (String) —

    An IP address. Used when attempting to fix geolocation based off of the user's IP address.

  • :granularity (String) — default: 'neighborhood' —

    This is the minimal granularity of place types to return and must be one of: 'poi', 'neighborhood', 'city', 'admin' or 'country'.

  • :accuracy (String) — default: '0m' —

    A hint on the "region" in which to search. If a number, then this is a radius in meters, but it can also take a string that is suffixed with ft to specify feet. If coming from a device, in practice, this value is whatever accuracy the device has measuring its location (whether it be coming from a GPS, WiFi triangulation, etc.).

  • :max_results (Integer) —

    A hint as to the number of results to return. This does not guarantee that the number of results returned will equal max_results, but instead informs how many "nearby" results to return. Ideally, only pass in the number of places you intend to display to the user here.

  • :contained_within (String) —

    This is 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.

  • :"attribute:street_address" (String) —

    This option searches for places which have this given street address. There are other well-known and application-specific attributes available. Custom attributes are also permitted.

Returns:

See Also:

Rate Limited?:

  • Yes

Requires Authentication?:

  • No



27
28
29
30
31
 
# File 'lib/twitter/client/places_and_geo.rb', line 27

def places_nearby(options={})
  get("/1/geo/search.json", options)['result']['places'].map do |place|
    Twitter::Place.new(place)
  end
end

#places_similar(options = {}) ⇒ Array<Twitter::Place>

Note:

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 Geo#place to create a new one. The token contained in the response is the token necessary to create a new place.

Locates places near the given coordinates which are similar in name

Examples:

Return an array of places similar to Twitter HQ

Twitter.places_similar(:lat => "37.7821120598956", :long => "-122.400612831116", :name => "Twitter HQ")

Parameters:

  • options (Hash) (defaults to: {}) —

    A customizable set of options.

Options Hash (options):

  • :lat (Float) —

    The latitude to search around. This option will be ignored unless it is inside the range -90.0 to +90.0 (North is positive) inclusive. It will also be ignored if there isn't a corresponding :long option.

  • :long (Float) —

    The longitude to search around. The valid range for longitude is -180.0 to +180.0 (East is positive) inclusive. This option will be ignored if outside that range, if it is not a number, if geo_enabled is disabled, or if there not a corresponding :lat option.

  • :name (String) —

    The name a place is known as.

  • :contained_within (String) —

    This is 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.

  • :"attribute:street_address" (String) —

    This option searches for places which have this given street address. There are other well-known and application-specific attributes available. Custom attributes are also permitted.

Returns:

See Also:

Rate Limited?:

  • Yes

Requires Authentication?:

  • No



49
50
51
52
53
 
# File 'lib/twitter/client/places_and_geo.rb', line 49

def places_similar(options={})
  get("/1/geo/similar_places.json", options)['result']['places'].map do |place|
    Twitter::Place.new(place)
  end
end

#reverse_geocode(options = {}) ⇒ Array<Twitter::Place>

Note:

This request is an informative call and will deliver generalized results about geography.

Searches for up to 20 places that can be used as a place_id

Examples:

Return an array of places within the specified region

Twitter.reverse_geocode(:lat => "37.7821120598956", :long => "-122.400612831116")

Parameters:

  • options (Hash) (defaults to: {}) —

    A customizable set of options.

Options Hash (options):

  • :lat (Float) —

    The latitude to search around. This option will be ignored unless it is inside the range -90.0 to +90.0 (North is positive) inclusive. It will also be ignored if there isn't a corresponding :long option.

  • :long (Float) —

    The longitude to search around. The valid range for longitude is -180.0 to +180.0 (East is positive) inclusive. This option will be ignored if outside that range, if it is not a number, if geo_enabled is disabled, or if there not a corresponding :lat option.

  • :accuracy (String) — default: '0m' —

    A hint on the "region" in which to search. If a number, then this is a radius in meters, but it can also take a string that is suffixed with ft to specify feet. If coming from a device, in practice, this value is whatever accuracy the device has measuring its location (whether it be coming from a GPS, WiFi triangulation, etc.).

  • :granularity (String) — default: 'neighborhood' —

    This is the minimal granularity of place types to return and must be one of: 'poi', 'neighborhood', 'city', 'admin' or 'country'.

  • :max_results (Integer) —

    A hint as to the number of results to return. This does not guarantee that the number of results returned will equal max_results, but instead informs how many "nearby" results to return. Ideally, only pass in the number of places you intend to display to the user here.

Returns:

See Also:

Rate Limited?:

  • Yes

Requires Authentication?:

  • No



70
71
72
73
74
 
# File 'lib/twitter/client/places_and_geo.rb', line 70

def reverse_geocode(options={})
  get("/1/geo/reverse_geocode.json", options)['result']['places'].map do |place|
    Twitter::Place.new(place)
  end
end