From 227cfc5cff0bd8f9004be9731ded76da43d5d200 Mon Sep 17 00:00:00 2001
From: Kumar Appaiah <a.kumar@alumni.iitm.ac.in>
Date: Sun, 18 Apr 2010 17:03:52 -0500
Subject: [PATCH] Added reverse_geocode, nearby_places, and geo_id methods.

---
 doc/api.rst   | 41 ++++++++++++++++++++++++++++++++++++++++-
 tests.py      |  5 +++++
 tweepy/api.py | 23 ++++++++++++++++++++++-
 3 files changed, 67 insertions(+), 2 deletions(-)

diff --git a/doc/api.rst b/doc/api.rst
index 76980b6..11a3b20 100644
--- a/doc/api.rst
+++ b/doc/api.rst
@@ -142,7 +142,7 @@ Status methods
    :rtype: :class:`Status` object
 
 
-.. method:: API.update_status(status, [in_reply_to_status_id], [lat], [long], [source])
+.. method:: API.update_status(status, [in_reply_to_status_id], [lat], [long], [source], [place_id])
 
    Update the authenticated user's status. Statuses that are duplicates
    or too long will be silently ignored.
@@ -152,6 +152,7 @@ Status methods
    :param lat: The location's latitude that this tweet refers to.
    :param long: The location's longitude that this tweet refers to.
    :param source: Source of the update. Only supported by Identi.ca. Twitter ignores this parameter.
+   :param id: Twitter ID of location which is listed in the Tweet if geolocation is enabled for the user.
    :rtype: :class:`Status` object
 
 
@@ -825,4 +826,42 @@ Local Trends Methods
    :param woeid:     * The WOEID of the location to be querying for.
    :rtype: :class:`JSON` object
 
+Geo Methods
+-----------
 
+.. method:: API.reverse_geocode([lat], [long], [accuracy], [granularity], [max_results])
+
+   Given a latitude and longitude, looks for places (cities and
+   neighbourhoods) whose IDs can be specified in a call to
+   :func:`update_status` to appear as the name of the location. This
+   call provides a detailed response about the location in question;
+   the :func:`nearby_places` function should be preferred for getting
+   a list of places nearby without great detail.
+
+   :param lat: The location's latitude.
+   :param long: The location's longitude.
+   :param accuracy: Specify the "region" in which to search, such as 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 this is not passed in, then it is assumed to be 0m
+   :param granularity: Assumed to be `neighborhood' by default; can also be `city'.
+   :param max_results: A hint as to the maximum number of results to return. This is only a guideline, which may not be adhered to.
+
+.. method:: API.reverse_geocode([lat], [long], [ip], [accuracy], [granularity], [max_results])
+
+   Given a latitude and longitude, looks for nearby places (cities and
+   neighbourhoods) whose IDs can be specified in a call to
+   :func:`update_status` to appear as the name of the location. This
+   call provides a detailed response about the location in question;
+   the :func:`nearby_places` function should be preferred for getting
+   a list of places nearby without great detail.
+
+   :param lat: The location's latitude.
+   :param long: The location's longitude.
+   :param ip: The location's IP address. Twitter will attempt to geolocate using the IP address.
+   :param accuracy: Specify the "region" in which to search, such as 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 this is not passed in, then it is assumed to be 0m
+   :param granularity: Assumed to be `neighborhood' by default; can also be `city'.
+   :param max_results: A hint as to the maximum number of results to return. This is only a guideline, which may not be adhered to.
+
+.. method:: API.geo_id(id)
+
+   Given *id* of a place, provide more details about that place.
+
+   :param id: Valid Twitter ID of a location.
diff --git a/tests.py b/tests.py
index f2c735f..75911b4 100644
--- a/tests.py
+++ b/tests.py
@@ -266,6 +266,11 @@ class TweepyAPITests(unittest.TestCase):
         self.api.trends_daily()
         self.api.trends_weekly()
 
+    def testgeoapis(self):
+        self.api.geo_id(id='c3f37afa9efcf94b') # Austin, TX, USA
+        self.api.nearby_places(lat=30.267370168467806, long=-97.74261474609375) # Austin, TX, USA
+        self.api.reverse_geocode(lat=30.267370168467806, long=-97.74261474609375) # Austin, TX, USA
+
 """
 class TweepyCursorTests(unittest.TestCase):
 
diff --git a/tweepy/api.py b/tweepy/api.py
index 55d7eb5..c9ba04b 100644
--- a/tweepy/api.py
+++ b/tweepy/api.py
@@ -122,7 +122,7 @@ class API(object):
         path = '/statuses/update.json',
         method = 'POST',
         payload_type = 'status',
-        allowed_param = ['status', 'in_reply_to_status_id', 'lat', 'long', 'source'],
+        allowed_param = ['status', 'in_reply_to_status_id', 'lat', 'long', 'source', 'place_id'],
         require_auth = True
     )
 
@@ -661,6 +661,27 @@ class API(object):
         allowed_param = ['date', 'exclude']
     )
 
+    """ geo/reverse_geocode """
+    reverse_geocode = bind_api(
+        path = '/geo/reverse_geocode.json',
+        payload_type = 'json',
+        allowed_param = ['lat', 'long', 'accuracy', 'granularity', 'max_results']
+    )
+
+    """ geo/nearby_places """
+    nearby_places = bind_api(
+        path = '/geo/nearby_places.json',
+        payload_type = 'json',
+        allowed_param = ['lat', 'long', 'ip', 'accuracy', 'granularity', 'max_results']
+    )
+
+    """ geo/id """
+    geo_id = bind_api(
+        path = '/geo/id/{id}.json',
+        payload_type = 'json',
+        allowed_param = ['id']
+    )
+
     """ Internal use only """
     @staticmethod
     def _pack_image(filename, max_size):
-- 
2.25.1