Photo by Nebarnix

Twitter's Search API is fantastic, but unlike the UI version they don't support using the name of a place to limit your results, only latitude and longitude. I couldn't ask my users to type in coordinates for searches, so I needed some way to translate the names into the form Twitter wants.

The process of converting from human names into coordinates is known as geocoding, and luckily there's some great free web APIs that will do the job for you. I chose Yahoo's GeoPlanet, they allow up 50,000 requests a month, and Tyler Hall has a great PHP wrapper ready to use.

I couldn't find a good example of actually using GeoPlanet in PHP, so I decided to kill two birds with one stone and publish my code as sample code for geocoding, and offer an off-the-shelf solution for anyone else who needs 'near' for Twitter searching. You can download geosearch.php
, and it's included below.

<?php

// Example demonstrating how to use Yahoo's Geoplanet API (via Tyler Hall's PHP wrapper)

// to emulate the 'near' parameter that's available in the Twitter search UI, but not

// through the API.

//

// To install it:

// 1) Put this file and class.geoplanet.php on your server

// 2) Get a free application ID from Yahoo – http://developer.yahoo.com/geo/

// 3) Copy the ID where this file has <Put your own app id in here>

// 4) Remove the die() statement just above it

//

// To use it:

// Call the URL of the file as you would http://search.twitter.com/search.atom

// All the normal supported arguments are passed through to Twitter's API

// If 'near=' is specified, then the place name string is passed to Geoplanet

// The latitude and longitude of the result are passed as 'geocode=' to Twitter

// If you also specify 'radius=' then that is passed, otherwise '25km' is used

//

// Gotchas:

// – It uses a redirect header, so for command-line curl you'll need -L to follow

// – There's zero error or exception handling

//

// Example:

// http://yourserver.com/geosearch.php?q=biking&near=boulder&radius=15km

require_once("class.geoplanet.php");

// If the named parameter was present on the input URL, append it to $url

function copy_url_input($name, $url)

{

if (isset($_GET[$name]))

$url .= "$name=".urlencode($_GET[$name])."&";

return $url;

}

$searchurl = "http://search.twitter.com/search.atom?&quot;;

// If the near parameter is present, then call Geoplanet to turn it into lat,long

if (isset($_GET['near']))

{

$placename = $_GET['near'];

die('You need to put your own app id here and then remove this statement');

$geoplanet = new GeoPlanet('<Put your own app id in here>');

$placelist = $geoplanet->getPlaces($placename);

$topplace = $placelist[0];

$centroid = $topplace['centroid'];

$lat = $centroid['lat'];

$lng = $centroid['lng'];

// The radius parameter is optional. If it's not present then default to 25km

if (isset($_GET['radius']))

$radius = $_GET['radius'];

else

$radius = '25km';

$searchurl .= "geocode=".urlencode("$lat,$lng,$radius")."&";

}

else

{

$searchurl = copy_url_input('geocode', $searchurl);

}

$searchurl = copy_url_input('q', $searchurl);

$searchurl = copy_url_input('lang', $searchurl);

$searchurl = copy_url_input('rpp', $searchurl);

$searchurl = copy_url_input('page', $searchurl);

$searchurl = copy_url_input('sinceid', $searchurl);

$searchurl = copy_url_input('show_user', $searchurl);

// Request a redirect to the URL with the lat,long added

header("Location: ".$searchurl);

?>