General README
==============

= Data Sources =
* iso639Languages: http://download.geonames.org/export/dump/iso-languagecodes.txt
* countries: http://download.geonames.org/export/dump/countryInfo.txt
* ADM1:
** http://download.geonames.org/export/dump/admin1Codes.txt (not used anymore)
** http://download.geonames.org/export/dump/admin1CodesASCII.txt
* ADM2:
** http://download.geonames.org/export/dump/admin2Codes.txt

= Features =
* Access ISO-639 Languages
* Access Countries, with their currency, and more
* Access First and Second order administrative divisions
* Full-text search of places (cities)
* GIS "near" search of places (cities)

= Limitations =
* We do not import ADM3 and ADM4
* no work around the 10-result limitation of stock gisgraphy (needs a patched gisgraphy to get more results)
* childAdministrativeDivisions() returns all children. No way to add additional filters. 
* no lazy alternate names fetcher for geolocresults (so, we have no alternate names for geoloc results)
* uses FULL => slower than required. LONG does not return alternate names (contrary to gisgraphy documentation)
* we do not support the weird family language codes, so we are ignoring the alternate names that rely on these language codes


= Low-priority Ideas for the future =
* Entities: add hasSameIdentityAs, hasSameContentAs ?
* add getDisplayName (ULocale) calls for Language, Country
* googleMapUrl, yahooMapUrl ?
* Fetch lookup data from the internet (rather than classpath)
* replace static language names and country names with calls to ICU4J ULocale + give option to translate to other languages
* replace currency with information from ICU4J locale (or CLDR)
* Find a source of phone prefixes for cities

* Create an OSM-based (+ geonames ?) Place search service
** Extract Administrative Divisions hierarchy
** Extract Administrative Divisions boundaries
** Extract City names
** Extract City boundaries
** Find a way to map the cities to their timezone
** Extract interesting amenities (metro, bus, grocery stores, ...)
** Map Geonames ADMs to OSM Nodes, ways and relations
** Map Geonames IDs to OSM place nodes
** Find a way to refer to stable OSM node identifiers...

Developer README
================
= Dependencies =
OpenPlaceSearch depends on a number of libraries :
* Joda-Time
* Guava-IO (until Scala-IO is merged to the official scala: https://github.com/scala-incubator/scala-io)
* HC-Helpers
* IBM icu4j


= How to update the reference data =
* git status # make sure the tree is clean (in case things don't go smooth)
* $ referencedata/update
* sbt test
* git status # sanity check
* git commit -m "updated the reference data"


= Import as an idea project =

* sbt idea 
* import the project under intellij


Other interesting datasources that could be helpful
* Yahoo GeoPlanet
* GADM http://www.gadm.org/
* ADM2 boundaries : http://www.unsalb.org/
* ADM1 : http://wwwn.cdc.gov/epiinfo/

* Population: http://sedac.ciesin.columbia.edu/gpw/


= Release Procedure =
* git tag v0.x
* git push --tags origin
* git publish
* bump version number