Source for file places.php

Documentation is available at places.php

  1. <?php
  2. /**
  3.  * @package     Joomla.Platform
  4.  * @subpackage  Twitter
  5.  *
  6.  * @copyright   Copyright (C) 2005 - 2013 Open Source Matters, Inc. All rights reserved.
  7.  * @license     GNU General Public License version 2 or later; see LICENSE
  8.  */
  9.  
  10. defined('JPATH_PLATFORM') or die();
  11.  
  12. /**
  13.  * Twitter API Places & Geo class for the Joomla Platform.
  14.  *
  15.  * @package     Joomla.Platform
  16.  * @subpackage  Twitter
  17.  * @since       12.3
  18.  */
  19. class JTwitterPlaces extends JTwitterObject
  20. {
  21.     /**
  22.      * Method to get all the information about a known place.
  23.      *
  24.      * @param   string  $id  A place in the world. These IDs can be retrieved using getGeocode.
  25.      *
  26.      * @return  array  The decoded JSON response
  27.      *
  28.      * @since   12.3
  29.      */
  30.     public function getPlace($id)
  31.     {
  32.         // Check the rate limit for remaining hits
  33.         $this->checkRateLimit('geo', 'id/:place_id');
  34.  
  35.         // Set the API path
  36.         $path = '/geo/id/' . $id . '.json';
  37.  
  38.         // Send the request.
  39.         return $this->sendRequest($path);
  40.     }
  41.  
  42.     /**
  43.      * Method to get up to 20 places that can be used as a place_id when updating a status.
  44.      *
  45.      * @param   float    $lat          The latitude to search around.
  46.      * @param   float    $long         The longitude to search around.
  47.      * @param   string   $accuracy     A hint on the "region" in which to search. If a number, then this is a radius in meters,
  48.      *                                     but it can also take a string that is suffixed with ft to specify feet.
  49.      * @param   string   $granularity  This is the minimal granularity of place types to return and must be one of: poi, neighborhood,
  50.      *                                     city, admin or country.
  51.      * @param   integer  $max_results  A hint as to the number of results to return.
  52.      * @param   string   $callback     If supplied, the response will use the JSONP format with a callback of the given name.
  53.      *
  54.      * @return  array  The decoded JSON response
  55.      *
  56.      * @since   12.3
  57.      */
  58.     public function getGeocode($lat, $long, $accuracy = null, $granularity = null, $max_results = 0, $callback = null)
  59.     {
  60.         // Check the rate limit for remaining hits
  61.         $this->checkRateLimit('geo', 'reverse_geocode');
  62.  
  63.         // Set the API path
  64.         $path = '/geo/reverse_geocode.json';
  65.  
  66.         // Set the request parameters
  67.         $data['lat'] = $lat;
  68.         $data['long'] = $long;
  69.  
  70.         // Check if accuracy is specified
  71.         if ($accuracy)
  72.         {
  73.             $data['accuracy'] = $accuracy;
  74.         }
  75.  
  76.         // Check if granularity is specified
  77.         if ($granularity)
  78.         {
  79.             $data['granularity'] = $granularity;
  80.         }
  81.  
  82.         // Check if max_results is specified
  83.         if ($max_results)
  84.         {
  85.             $data['max_results'] = $max_results;
  86.         }
  87.  
  88.         // Check if callback is specified
  89.         if ($callback)
  90.         {
  91.             $data['callback'] = $callback;
  92.         }
  93.  
  94.         // Send the request.
  95.         return $this->sendRequest($path, 'GET', $data);
  96.     }
  97.  
  98.     /**
  99.      * Method to search for places that can be attached to a statuses/update.
  100.      *
  101.      * @param   float    $lat          The latitude to search around.
  102.      * @param   float    $long         The longitude to search around.
  103.      * @param   string   $query        Free-form text to match against while executing a geo-based query, best suited for finding nearby
  104.      *                                     locations by name.
  105.      * @param   string   $ip           An IP address.
  106.      * @param   string   $granularity  This is the minimal granularity of place types to return and must be one of: poi, neighborhood, city,
  107.      *                                     admin or country.
  108.      * @param   string   $accuracy     A hint on the "region" in which to search. If a number, then this is a radius in meters, but it can
  109.      *                                     also take a string that is suffixed with ft to specify feet.
  110.      * @param   integer  $max_results  A hint as to the number of results to return.
  111.      * @param   string   $within       This is the place_id which you would like to restrict the search results to.
  112.      * @param   string   $attribute    This parameter searches for places which have this given street address.
  113.      * @param   string   $callback     If supplied, the response will use the JSONP format with a callback of the given name.
  114.      *
  115.      * @return  array  The decoded JSON response
  116.      *
  117.      * @since   12.3
  118.      * @throws  RuntimeException
  119.      */
  120.     public function search($lat = null, $long = null, $query = null, $ip = null, $granularity = null, $accuracy = null, $max_results = 0,
  121.         $within = null, $attribute = null, $callback = null)
  122.     {
  123.         // Check the rate limit for remaining hits
  124.         $this->checkRateLimit('geo', 'search');
  125.  
  126.         // Set the API path
  127.         $path = '/geo/search.json';
  128.  
  129.         // At least one of the following parameters must be provided: lat, long, ip, or query.
  130.         if ($lat == null && $long == null && $ip == null && $query == null)
  131.         {
  132.             throw new RuntimeException('At least one of the following parameters must be provided: lat, long, ip, or query.');
  133.         }
  134.  
  135.         // Check if lat is specified.
  136.         if ($lat)
  137.         {
  138.             $data['lat'] = $lat;
  139.         }
  140.  
  141.         // Check if long is specified.
  142.         if ($long)
  143.         {
  144.             $data['long'] = $long;
  145.         }
  146.  
  147.         // Check if query is specified.
  148.         if ($query)
  149.         {
  150.             $data['query'] = rawurlencode($query);
  151.         }
  152.  
  153.         // Check if ip is specified.
  154.         if ($ip)
  155.         {
  156.             $data['ip'] = $ip;
  157.         }
  158.  
  159.         // Check if granularity is specified
  160.         if ($granularity)
  161.         {
  162.             $data['granularity'] = $granularity;
  163.         }
  164.  
  165.         // Check if accuracy is specified
  166.         if ($accuracy)
  167.         {
  168.             $data['accuracy'] = $accuracy;
  169.         }
  170.  
  171.         // Check if max_results is specified
  172.         if ($max_results)
  173.         {
  174.             $data['max_results'] = $max_results;
  175.         }
  176.  
  177.         // Check if within is specified
  178.         if ($within)
  179.         {
  180.             $data['contained_within'] = $within;
  181.         }
  182.  
  183.         // Check if attribute is specified
  184.         if ($attribute)
  185.         {
  186.             $data['attribute:street_address'] = rawurlencode($attribute);
  187.         }
  188.  
  189.         // Check if callback is specified
  190.         if ($callback)
  191.         {
  192.             $data['callback'] = $callback;
  193.         }
  194.  
  195.         // Send the request.
  196.         return $this->sendRequest($path, 'GET', $data);
  197.     }
  198.  
  199.     /**
  200.      * Method to locate places near the given coordinates which are similar in name.
  201.      *
  202.      * @param   float   $lat        The latitude to search around.
  203.      * @param   float   $long       The longitude to search around.
  204.      * @param   string  $name       The name a place is known as.
  205.      * @param   string  $within     This is the place_id which you would like to restrict the search results to.
  206.      * @param   string  $attribute  This parameter searches for places which have this given street address.
  207.      * @param   string  $callback   If supplied, the response will use the JSONP format with a callback of the given name.
  208.      *
  209.      * @return  array  The decoded JSON response
  210.      *
  211.      * @since   12.3
  212.      */
  213.     public function getSimilarPlaces($lat, $long, $name, $within = null, $attribute = null, $callback = null)
  214.     {
  215.         // Check the rate limit for remaining hits
  216.         $this->checkRateLimit('geo', 'similar_places');
  217.  
  218.         // Set the API path
  219.         $path = '/geo/similar_places.json';
  220.  
  221.         $data['lat'] = $lat;
  222.         $data['long'] = $long;
  223.         $data['name'] = rawurlencode($name);
  224.  
  225.         // Check if within is specified
  226.         if ($within)
  227.         {
  228.             $data['contained_within'] = $within;
  229.         }
  230.  
  231.         // Check if attribute is specified
  232.         if ($attribute)
  233.         {
  234.             $data['attribute:street_address'] = rawurlencode($attribute);
  235.         }
  236.  
  237.         // Check if callback is specified
  238.         if ($callback)
  239.         {
  240.             $data['callback'] = $callback;
  241.         }
  242.  
  243.         // Send the request.
  244.         return $this->sendRequest($path, 'GET', $data);
  245.     }
  246.  
  247.     /**
  248.      * Method to create a new place object at the given latitude and longitude.
  249.      *
  250.      * @param   float   $lat        The latitude to search around.
  251.      * @param   float   $long       The longitude to search around.
  252.      * @param   string  $name       The name a place is known as.
  253.      * @param   string  $geo_token  The token found in the response from geo/similar_places.
  254.      * @param   string  $within     This is the place_id which you would like to restrict the search results to.
  255.      * @param   string  $attribute  This parameter searches for places which have this given street address.
  256.      * @param   string  $callback   If supplied, the response will use the JSONP format with a callback of the given name.
  257.      *
  258.      * @return  array  The decoded JSON response
  259.      *
  260.      * @since   12.3
  261.      */
  262.     public function createPlace($lat, $long, $name, $geo_token, $within, $attribute = null, $callback = null)
  263.     {
  264.         // Check the rate limit for remaining hits
  265.         $this->checkRateLimit('geo', 'place');
  266.  
  267.         $data['lat'] = $lat;
  268.         $data['long'] = $long;
  269.         $data['name'] = rawurlencode($name);
  270.         $data['token'] = $geo_token;
  271.         $data['contained_within'] = $within;
  272.  
  273.         // Check if attribute is specified
  274.         if ($attribute)
  275.         {
  276.             $data['attribute:street_address'] = rawurlencode($attribute);
  277.         }
  278.  
  279.         // Check if callback is specified
  280.         if ($callback)
  281.         {
  282.             $data['callback'] = $callback;
  283.         }
  284.  
  285.         // Set the API path
  286.         $path = '/geo/place.json';
  287.  
  288.         // Send the request.
  289.         return $this->sendRequest($path, 'POST', $data);
  290.     }
  291. }

Documentation generated on Tue, 19 Nov 2013 15:10:41 +0100 by phpDocumentor 1.4.3