tag-e-geo
v1.7.0
Published
Create Tags based on Geonames hierarchy
Downloads
10
Readme
Lambda Taggable Geonames (AKA "TAG-E")
Why?
Locating Hotels and other content by searching for a place name is the heart of the Tagging system. We use Geonames to "reverse geocode" the Lat/Lon for each Hotel in the database and add "hierarchy" for that place.
See: How? > Detail section for detailed example
What?
Lambda function that accepts a set of Longitude & Latitude coordinates (lat/lon) and returns a list of Geo Tags. (corresponding to the elements in the Geonames hierarchy for that lat/lon).
How?
There are two ways to use this package:
Lambda
Deploy the Lambda function by running the deployment script:
npm run deploy
( see: https://github.com/numo-labs/aws-lambda-deploy for detail )Invoke in AWS Console:
Sample Event
{
"_id": "hotel:mhid.02tu1jz",
"displayName": "Elvis Presley's Heartbreak",
"location": {
"lat": "35.04850",
"lon": "-90.02710"
},
"tags": []
}Will return an array of Geo Tags in the Taggable System format:
[
{
"_id": "geo:geonames.6295630",
"displayName": "Earth",
"location": {
"lat": "0",
"lon": "0"
},
"tags": [],
"markets": {
"de": {
"de": {
"label": "search",
"values": [
"Welt"
]
}
},
"gb": {
"en": {
"label": "search",
"values": [
"World"
]
}
},
"es": {
"es": {
"label": "search",
"values": [
"Tierra"
]
}
},
"fi": {
"fi": {
"label": "search",
"values": [
"Maa"
]
}
},
"fr": {
"fr": {
"label": "search",
"values": [
"Terre"
]
}
},
"nl": {
"nl": {
"label": "search",
"values": [
"Aarde"
]
}
},
"no": {
"no": {
"label": "search",
"values": [
"Jorden"
]
}
},
"ru": {
"ru": {
"label": "search",
"values": [
"Земля"
]
}
}
}
},
{
"_id": "geo:geonames.6255149",
"displayName": "North America",
"location": {
"lat": "46.07323",
"lon": "-100.54688"
},
"tags": [
{
"node": "geo:geonames.6295630",
"edge": "LOCATED_IN",
"displayName": "Earth",
"source": "geonames",
"active": true
}
],
"markets": {
"dk": {
"da": {
"label": "search",
"values": [
"Nordamerika"
]
}
},
"de": {
"de": {
"label": "search",
"values": [
"Nordamerika"
]
}
},
"gb": {
"en": {
"label": "search",
"values": [
"North America"
]
}
},
"es": {
"es": {
"label": "search",
"values": [
"Norteamérica"
]
}
},
"fi": {
"fi": {
"label": "search",
"values": [
"Pohjois-Amerikka"
]
}
},
"fr": {
"fr": {
"label": "search",
"values": [
"Amérique du Nord"
]
}
},
"nl": {
"nl": {
"label": "search",
"values": [
"Noord-Amerika"
]
}
},
"no": {
"no": {
"label": "search",
"values": [
"Nord-Amerika"
]
}
},
"ru": {
"ru": {
"label": "search",
"values": [
"Северная Америка"
]
}
},
"sv": {
"sv": {
"label": "search",
"values": [
"Nordamerika"
]
}
},
"cn": {
"zh": {
"label": "search",
"values": [
"北美洲"
]
}
}
}
},
{
"_id": "geo:geonames.6252001",
"displayName": "United States",
"location": {
"lat": "39.76",
"lon": "-98.5"
},
"tags": [
{
"node": "geo:geonames.6255149",
"edge": "LOCATED_IN",
"displayName": "North America",
"source": "geonames",
"active": true
}
],
"markets": {
"dk": {
"da": {
"label": "search",
"values": [
"USA"
]
}
},
"de": {
"de": {
"label": "search",
"values": [
"Vereinigte Staaten"
]
}
},
"gb": {
"en": {
"label": "search",
"values": [
"United States of America"
]
}
},
"es": {
"es": {
"label": "search",
"values": [
"Estados Unidos"
]
}
},
"fi": {
"fi": {
"label": "search",
"values": [
"Yhdysvallat"
]
}
},
"fr": {
"fr": {
"label": "search",
"values": [
"USA"
]
}
},
"nl": {
"nl": {
"label": "search",
"values": [
"Verenigde Staten"
]
}
},
"no": {
"no": {
"label": "search",
"values": [
"USA"
]
}
},
"ru": {
"ru": {
"label": "search",
"values": [
"США"
]
}
},
"sv": {
"sv": {
"label": "search",
"values": [
"USA"
]
}
},
"cn": {
"zh": {
"label": "search",
"values": [
"美国"
]
}
}
}
},
{
"_id": "geo:geonames.4662168",
"displayName": "Tennessee",
"location": {
"lat": "35.75035",
"lon": "-86.25027"
},
"tags": [
{
"node": "geo:geonames.6252001",
"edge": "LOCATED_IN",
"displayName": "United States",
"source": "geonames",
"active": true
}
],
"markets": {
"gb": {
"en": {
"label": "search",
"values": [
"Volunteer State"
]
}
},
"es": {
"es": {
"label": "search",
"values": [
"Tennessee"
]
}
},
"ru": {
"ru": {
"label": "search",
"values": [
"Теннесси"
]
}
},
"cn": {
"zh": {
"label": "search",
"values": [
"田纳西州"
]
}
}
}
},
{
"_id": "geo:geonames.4657046",
"displayName": "Shelby County",
"location": {
"lat": "35.184",
"lon": "-89.8956"
},
"tags": [
{
"node": "geo:geonames.4662168",
"edge": "LOCATED_IN",
"displayName": "Tennessee",
"source": "geonames",
"active": true
}
],
"markets": {
"es": {
"es": {
"label": "search",
"values": [
"Condado de Shelby"
]
}
},
"fr": {
"fr": {
"label": "search",
"values": [
"Comté de Shelby"
]
}
},
"ru": {
"ru": {
"label": "search",
"values": [
"Шелби"
]
}
},
"cn": {
"zh": {
"label": "search",
"values": [
"謝爾比縣"
]
}
}
}
},
{
"_id": "geo:geonames.4645760",
"displayName": "Nonconnah",
"location": {
"lat": "35.06204",
"lon": "-90.0362"
},
"tags": [
{
"node": "geo:geonames.4657046",
"edge": "LOCATED_IN",
"displayName": "Shelby County",
"source": "geonames",
"active": true
}
]
}
]Node Module
If you prefer to use this package as a node module e.g: as part of another lambda
npm install lambda-taggable-geonames-indexer --saveThen in your code:
var geonames = require('lambda-taggable-geonames-indexer');
var lat = '28.3852';
var lon = '81.5639';
geonames.find(lat, lon, function (err, geo) {
console.log(geo); // see Detail section below for example output
var geonames_id = geo.geonames[0].geonameId;
geonames.hierarchy(geonames_id, function (err, hierarchy) {
console.log(JSON.stringify(hierarchy, null, 2));
}); // see Detail for example hierarchy object
});Detail
The best way to understand how this works is with a simple example:
Imagine we have a Hotel in Formenterra
{
"MID": "1234ABCD",
"Name": "Blanco Hotel Formentera",
"Country": "SPAIN",
"ISO-2": "ES",
"Address": "Calle Fonoll Marí, 50 07871 Es Pujols",
"Latitude": "38.7",
"Longitude": "1.467"
}We would lookup this hotel in Geonames given its Latitude and Longitude
values using the following query:
http://api.geonames.org/findNearbyPlaceNameJSON?lat=38.7&lng=1.467&username=demo&style=full&localCountry=true&maxrows=100&cities=15000
{
"geonames":[
{
"distance":"1.31434",
"timezone":{
"gmtOffset":1,
"timeZoneId":"Europe/Madrid",
"dstOffset":2
},
"asciiName":"Sant Ferran de ses Roques",
"countryId":"2510769",
"fcl":"P",
"adminId2":"6424360",
"adminId3":"6356033",
"countryCode":"ES",
"adminId1":"2521383",
"lat":"38.70762",
"fcode":"PPL",
"continentCode":"EU",
"elevation":0,
"adminCode2":"PM",
"adminCode3":"07024",
"adminCode1":"07",
"lng":"1.45543",
"geonameId":6696037,
"toponymName":"Sant Ferran de ses Roques",
"population":10757,
"adminName5":"",
"adminName4":"",
"adminName3":"Formentera",
"alternateNames":[
{
"name":"http://en.wikipedia.org/wiki/Sant_Ferran_de_ses_Roques",
"lang":"link"
}
],
"adminName2":"Balearic Islands",
"name":"Sant Ferran de ses Roques",
"fclName":"city, village,...",
"countryName":"Spain",
"fcodeName":"populated place",
"adminName1":"Balearic Islands"
}
]
}From this response get the geonameId which we can use to run the
hierarchy query:
http://api.geonames.org/hierarchyJSON?geonameId=6696037&username=demo
{
"geonames":[
{
"lng":"0",
"geonameId":6295630,
"name":"Earth",
"fclName":"parks,area, ...",
"toponymName":"Earth",
"fcodeName":"area",
"adminName1":"",
"lat":"0",
"fcl":"L",
"fcode":"AREA",
"population":6814400000
},
{
"lng":"9.14062",
"geonameId":6255148,
"name":"Europe",
"fclName":"parks,area, ...",
"toponymName":"Europe",
"fcodeName":"continent",
"adminName1":"",
"lat":"48.69096",
"fcl":"L",
"fcode":"CONT",
"population":0
},
{
"adminCode1":"00",
"lng":"-4",
"geonameId":2510769,
"toponymName":"Kingdom of Spain",
"countryId":"2510769",
"fcl":"A",
"population":46505963,
"countryCode":"ES",
"name":"Spain",
"fclName":"country, state, region,...",
"countryName":"Spain",
"fcodeName":"independent political entity",
"adminName1":"",
"lat":"40",
"fcode":"PCLI"
},
{
"adminCode1":"07",
"lng":"1.45871",
"geonameId":6356033,
"toponymName":"Formentera",
"countryId":"2510769",
"fcl":"A",
"population":10757,
"countryCode":"ES",
"name":"Formentera",
"fclName":"country, state, region,...",
"countryName":"Spain",
"fcodeName":"third-order administrative division",
"adminName1":"Balearic Islands",
"lat":"38.71905",
"fcode":"ADM3"
}
]
}Expected Environment Variables
Running the Lambda/Script
Using this script requires that you set a GEONAMES_USERNAMES environment variable (one or more usernames)
e.g:
export GEONAMES_USERNAME=yourusername,backupusername,etc
export GEONAMES_CACHE=geonames-cache
Deploying
Deploying to AWS requires that you set AWS_REGION and AWS_IAM_ROLE variables.
e.g:
export AWS_REGION=eu-west-1
export AWS_IAM_ROLE=arn:aws:iam::123456789:role/LambdaExecRolesee: https://github.com/numo-labs/aws-lambda-deploy#2-ensure-that-the-required-aws-environment-variables-are-set
Setup Geonames Account
To use this module you will require a Geonames account. If you have not already signed up, visit: http://www.geonames.org/login
Next, ensure that you have enabled the "Free Web Service" for your Geonames account:
Go to: http://www.geonames.org/manageaccount and scroll to the bottom of the page
you will see a link "Click here to enable" click it.
Once enabled you should see a confirmation message:
Now everything should work as expected.
Running low on Geonames API Calls/Credits?
see: https://github.com/numo-labs/lambda-taggable-geonames-indexer/issues/5
Tests
to run the tests for this project execute the following command in your terminal:
npm test