geographer

Geographer - Geographic information from place names
===================================================

Download with:
``
npm install -g geographer //installing globally means you set API username once
//or
npm install geographer //each project gets its own geographer installation
`

This module lets you get geographic inforamtion about cities and places in the
USA easily and conveniently.

There's a command line component which allows you to set your username (tied to
your Geonames API key). You can also just add it to the 'config.json' file
manually if that's your jam.

Full List of Setup Commands:
`
geographer -u YOUR_GEONAMES_USERNAME
geographer -l LANGUAGE_CODE //default set to 'en' for english
geographer -c YOUR_COUNTRY_CODE_OR_NAME //default set to 'US' or united states
//or
geo -u YOUR_USERNAME
geo -l LANGUAGE_CODE
geo -c YOUR_COUNTRY_CODE_OR_NAME
`

Instad of setting your username this way you can always just edit teh config.json file
directly. Your username is how the API links to your API key for the geonames API.

To work with these commands on only the current directory's copy of geographer use:
`
node_modules/.bin/geographer -u YOUR_GEONAMES_USERNAME
//or
node_modules/.bin/geo -u YOUR_GEONAMES_USERNAME
`

If you country is more than one word set it like so:
`
geo -c 'united states'
`
What do you need for this to work?
=================================

A Geonames username setup to work with the API key:

Go to http://www.geonames.org/manageaccount, create an account for free and then
click the button right underneath the signup form "enable for free web service."
It should take 1 hour for your key to activate for your chosen username.
Geonames doesn't give an exact number anywhere, I'd say anywhere around
2000 requests per hour should be fine.

If it's too confusing to set up or you need moral support just hit me up on twitter
handle @yvanscher, or if my module is a pile of donkey dung and you'd like
to tell me just how much better it could be tweet at me.

Usage
====
Setup:
`
geo -u YOUR_USERNAME
`
Call format:
`
//maxresults is optional
geographer('placename', 'statename/statecode', [maxresults], function(results){
console.log(results)
})
`
Example:
`
var geographer = require('geographer')

geographer('Ithaca', 'NY', 2, function(results){
console.log(results)
})
//or
geographer('Ithaca', 'new york', 2 , function(results){ //new york not case sensitive
console.log(results)
})

//returns

{ emptyfields: { 'Ithaca Tompkins Regional Airport': { '0': [Object] } },
terraindata:
{ potentialresults: 62,
Ithaca:
{ country: 'United States',
region: 'New York',
county: 'Tompkins County',
locationtype: 'seat of a second-order administrative division',
terraintype: 'city, village,...',
elevation: 125,
latitude: '42.44063',
longitude: '-76.49661',
boundingbox: [Object],
timezone: [Object],
population: 30014 },
'Ithaca Tompkins Regional Airport':
{ country: 'United States',
region: 'New York',
locationtype: 'airport',
terraintype: 'spot, building, farm',
elevation: 335,
latitude: '42.49083',
longitude: '-76.45833',
timezone: [Object]
}
}
}
`
Why does it get an airport as the second result? Clearly we asked for the city.
Since we set the finalparameter in our call to geographer('Ithaca', 'NY', 2)
to 2, geographer tries to get more places that might fit the description in
addition to the most likely result. This final parameter is optional and if left
blank or omitted all possible results will be returned. To just get the city of
Ithaca set the final parameter to 1.

Any fields that could not be found a location gets cleaned out of the terraindata
object and put into the emptyfields object with the location name as an index.
If you don't want that info just discard it.

Calling:
`
geographer('Ithaca', 'NY', function(results){})
``
Returns 62 results for locations that potentially match the name Ithaca. From most
likely desired to least likely desired.

In the Future
============
In the world of tommorrow I'm hoping to add the ability to create geonames API keys
and usernames directly from your code or command line. For now we have to use
Geonames functional website for signing up.I'm working on the ability to
exclude certain keywords forall queries or just from queries that
search for placename "ithaca." IT IS NOT IMPLEMENTED YET.

What is in the 'info' folder?
============================
Magical country codes, language codes, US states. Some are used
others are there for any future work on the project.