GPLplanet: A PHP repository from chrisboden

/**
 * @package gplplanet
 * @author Tyler Bell tylerwbell[at]gmail[dot]com
 * @copyright (C) 2009-2011 - Tyler Bell
 * @license GNU General Public License
 */

INTRODUCTION
-----------------------
GPLplanet: an open source PHP library to assist in employing local instances of Yahoo 
GeoPlanet(tm) in production. 
 
"Yahoo! GeoPlanet is a resource for managing all geo-permanent named places 
on Earth. It provides the geographic developer community with the vocabulary 
and grammar to describe the world's geography in an unequivocal, permanent, 
\and language-neutral manner. Developers can geo-enable their applications 
by using GeoPlanet to traverse the global spatial hierarchy, identify the 
geography relevant to their users and their businesses, and in turn, 
unambiguously geotag, geotarget, and geolocate data across the Web" 
http://developer.yahoo.com/geo/geoplanet/

Yahoo makes GeoPlanet available as both a Web service and data download.  
Due to call-per-day restrictions or latency concerns, small businesses and 
startups are either unwilling or unable to create their core geographic 
platforms on Yahoo Web services.   This library uses a local version of 
GeoPlanet to obtain similar functionality, in a local environment, allowing 
developers easy access to GeoPlanet in a PHP class with access to Web services 
where required.  In a nutshell:

- Creates highly optimized (read: not normalized) MySQL geoplanet database
- Imports GeoPlanet TSV
- Provides PHP wrappers for getParents(), getChildren(), disambiguate() etc. methods
- Wraps geocode(), reverseGeocode(), and getElevation() calls (Web Service only)
- Gets and caches coordinates for woeids (not supplied with data dump)
- Provides sample Web service scripts for deployment examples SaaS environments

These libraries are intended to make a local instance of GeoPlanet more accessible and easier to 
understand before implementing in production. If you are looking for a simple GeoPlanet
Web-service-only wrapper, see Tyler Hall's http://github.com/tylerhall/php-geoplanet/.
  
EXAMPLES
---------------------
require_once('class.geoengine.php');			
$engine = geoengine::getInstance();             //geoengine is a factory singleton
$engine->disambiguate("springfield");           //the most likely 'Springfield'
$engine->getChildren(31278);                    //children of woeid 31278 (Oxford, UK)
$engine->getElevationByWOEID(2461928);          //elevation of woeid 2461928 (Northfield, MN)
$engine->getByName("springfield","UK");         //all places called "Springfield" in UK
$engine->geocode("1 infinity loop, Cupertino, ca"); //geocodes
$engine->reverseGeocode(0.151490,52.145329);    //reverse geocodes
$engine->getBbox(727232);                       //bounding box of Amsterdam
$engine->filterByType($engine->getDescendants(23424977),7); //all towns in US
$engine->getAdjacencies(2468964);               //all towns surrounding woeid 2468964 (Pasedena, CA)

FILE OVERVIEW
-------------------------
class.geoengine.php         Core methods and factory class; instantiate as singleton
class.geoservice.php        Methods wrapping YQL calls; instantiated as singleton, when required, by geoengine
class.geo.php               Geo object representing named-place; instantiated as required by geoengine
import/class.import.php     Methods for tsv data import
import/import.php           Procedural script for importing tsv data
import/geo.sql              SQL script for creating database
config.ini                  Configurations incl. database connection
webservice/disambiguate.php Example script for getting most probably place of given name
webservice/navigate.php     Example script for obtaining parents, children, etc. from geoplanet
webservice/reversegeocode   Example script for reverse geocoding

IMPORTING GEOPLANET DATA
-------------------------
(1) Add database vars to config.ini
(2) Download geoplanet data from http://developer.yahoo.com/geo/geoplanet/data/
(3) Assign tsv filenames to the variables in import.php
(4) Run import.php from the command line (e.g. "php import.php")

Import Notes:
- Import status will be echoed
- Script takes several hours or even days, depending on processor
- 50GB HD space required for MySQL temporary tables during import process
- php.ini memory_limit +1GB
- MySQL max_allowed_packet required 20MB
- Largest array produced thereafter at runtime is just under 18MB (UK descendants)

TODO
--------------------------
- Siblings data optimization
- BelongTo service integration
- Name search JS code examples for as-you-type lookup
chrisboden/GPLplanet
