Permalink
Find file
Fetching contributors…
Cannot retrieve contributors at this time
89 lines (77 sloc) 4.46 KB
/**
* @package gplplanet
* @author Tyler Bell tylerwbell[at]gmail[dot]com
* @copyright (C) 2009,2010 - 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 wervice 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