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