{
// JSON REST services provided by geonames.org
// adapted from: http://www.geonames.org/export/JSON-webservices.html
// http://creativecommons.org/licenses/by/3.0/
// INCOMPLETE IMPLEMENTATION
"SMDVersion":"2.0",
"id":"/geonames",
"transport":"JSONP",
"envelope":"URL",
"target": "http://ws.geonames.org/",
"parameters" : [
{name:"type", optional: false, "default":"JSON"}
],
"services":{
getCountryInfo:{
// Result : returns info about a country such as name, population, etc.
// If country parameter is not specified, that information is returned for
// every country
"target": "countryInfoJSON",
"parameters": [
{ name: "country", type:"STRING", optional: true },
{ name: "lang", type:"STRING"}, // default: "en"
{ name: "maxRows", type:"INTEGER", optional: true } // default: 10
]
},
getCities:{
// Result : returns a list of cities and placenames in the bounding box,
// ordered by relevancy (capital/population). Placenames close together
// are filterered out and only the larger name is included in the resulting list.
"target": "citiesJSON",
"parameters": [
{ name: "north", type:"FLOAT"},
{ name: "south", type:"FLOAT"},
{ name: "east", type:"FLOAT"},
{ name: "west", type:"FLOAT"},
{ name: "lang", type:"STRING"}, // default: "en"
{ name: "maxRows", type:"INTEGER", optional: true } // deault: 10
]
},
"getQuakes":{
// Result : returns a list of earthquakes, ordered by magnitude
"target" : "earthquakesJSON",
"parameters" : [
// bounding box coords:
{ name: "north", type:"FLOAT" },
{ name: "south", type:"FLOAT" },
{ name: "east", type:"FLOAT" },
{ name: "west", type:"FLOAT" },
{ name: "date", type:"STRING",optional: true }, // yyyy-MM-dd
{ name: "minMagniture", type:"INTERGER",optional: true },
{ name: "maxRows", type:"INTEGER", optional: true } // deault: 10
]
},
"getWeather":{
// Weather data is provided in the METAR (METeorological Aerodrome Report) format.
// Result : returns a list of weather stations with the most recent weather observation
"target" : "weatherJSON",
"parameters" : [
{ name: "north", type:"FLOAT" },
{ name: "south", type:"FLOAT" },
{ name: "east", type:"FLOAT" },
{ name: "west", type:"FLOAT" },
{ name: "maxRows", type:"INTEGER",optional:true } // deault: 10
]
},
"getWeatherByICAO":{
// Result : returns the weather station and the most recent weather observation for the ICAO code
"target": "weatherIcaoJSON",
"parameters": [
{ name:"ICAO", type:"STRING" }
]
},
"getWeatherByCoords":{
// Result : returns a weather station with the most recent weather observation
"target": "findNearByWeatherJSON",
"parameters": [
{ name:"lat", type:"FLOAT" },
{ name:"lng", type:"FLOAT" }
]
},
"getChildren":{
// Returns the children for a given geonameId. The children are the
// administrative divisions within an other administrative division.
// Like the counties (ADM2) in a state (ADM1) or also the countries
// in a continent.
"target": "childrenJSON",
"parameters": [
{ name:"geonameId", type:"INTEGER" }
]
},
"getHierarchy":{
// Result : returns a list of GeoName records, ordered by hierarchy
// level. The top hierarchy (continent) is the first element in the list
"target": "hierarchyJSON",
"parameters": [
{ name:"geonameId", type:"INTEGER" }
]
},
"getNeighbours":{
// The neighbourhood for US cities. Data provided by Zillow under cc-by-sa license.
"target":"neighboursJSON",
"parameters": [
{ name:"geonameId", type:"INTEGER" }
//{ name:"lat", type:"FLOAT" },
//{ name:"long", type:"FLOAT" }
]
},
"getNeighbourhood":{
// returns the neighbourhood for the given latitude/longitude
// Example http://ws.geonames.org/neighbourhood?lat=40.78343&lng=-73.96625
"target":"neighbourhoodJSON",
"parameters":[
{ name:"lat", type:"FLOAT" },
{ name:"lng", type:"FLOAT" },
{ name:"radius", type:"FLOAT" }
]
},
"getSiblings":{
// Result : returns a list of GeoNames records that have the same
// administrative level and the same father
"target":"siblingsJSON",
"parameters": [
{ name:"geonameId", type:"INTEGER" }
]
},
"getCountryCode":{
// returns the iso country code for the given latitude/longitude
// With the parameter type=xml this service returns an xml document
// with iso country code and country name. The optional parameter
// lang can be used to specify the language the country name should
// be in. JSON output is produced with type=JSON
"target":"countryCode",
"parameters": [
{ name:"lat", type:"FLOAT" },
{ name:"lng", type:"FLOAT" },
{ name:"lang", type:"STRING",optional:true },
{ name:"radius", type:"FLOAT" }
]
},
"getCountrySubdivision":{
// returns the country and the administrative subdivison (state, province,...) for the given latitude/longitude
// Example http://ws.geonames.org/countrySubdivisionJSON?lat=47.03&lng=10.2
"target":"countrySubdivisionJSON",
"parameters":[
{ name:"lat", type:"FLOAT" },
{ name:"long", type:"FLOAT" },
{ name:"radius", type:"FLOAT" }
]
},
"getWikipediaBoundingBox":{
// returns the wikipedia entries within the bounding box as xml document
// Example http://ws.geonames.org/wikipediaBoundingBoxJSON?north=44.1&south=-9.9&east=-22.4&west=55.2
"target":"wikipediaBoundingBoxJSON",
"parameters":[
{ name: "north", type:"FLOAT" },
{ name: "south", type:"FLOAT" },
{ name: "east", type:"FLOAT" },
{ name: "west", type:"FLOAT" },
{ name: "lang", type:"STRING",optional:true }, // default: "en"
{ name: "maxRows", type:"INTEGER",optional:true } // default: 10
]
},
"searchWikipedia":{
// returns the wikipedia entries found for the searchterm as xml document
// Example http://ws.geonames.org/wikipediaSearchJSON?q=london&maxRows=10
"target":"wikipediaSearchJSON",
"parameters":[
{ name: "q", type:"STRING" }, // place name?
{ name: "title", type:"STRING" }, // optional
{ name: "lang", type:"FLOAT",optional:true }, // de or en
{ name: "maxRows", type:"INTEGER",optional:true } // default: 10
]
},
"getTimezone":{
// the timezone at the lat/lng with gmt offset (1. January) and dst offset (1. July)
"target":"timezoneJSON",
"parameters":[
{ name:"lat", type:"FLOAT" },
{ name:"lng", type:"FLOAT" }
]
},
"search":{
// returns the names found for the searchterm as xml or json document,
// the search is using an AND operator
"target":"searchJSON",
"parameters":[
// exhaustive list. see: http://www.geonames.org/export/geonames-search.html
{ name:"q", type:"STRING" },
{ name:"name", type:"STRING" },
{ name:"name_equals", type:"STRING" },
// optional:
{ name:"maxRows", type:"INTEGER",optional:true }, // def: 100, max:1000
{ name:"startRow", type:"INTEGER",optional:true }, // def: 0
{ name:"country", type:"STRING",optional:true }, // iso-3166, def: all
/* name:"adminCode..." */
{ name:"featureClass", type:"STRING",optional:true}, // ? multi, enum(a,h,l,p,r,s,t,u,v)
{ name:"featureCode", type:"STRING",optional:true},
{ name:"lang", type:"STRING",optional:true}, // iso-636
{ name:"type", type:"STRING",optional:true}, // xml | json | rdf, def: xml
{ name:"style", type:"STRING",optional:true }, // SHORT,MEDIUM,LONG,FULL def: MEDIUM
{ name:"isNamedRequired", type:"BOOLEAN", optional:true }
]
},
"postalCodeLookup":{
// returns a list of places for the given postalcode in JSON format
// Example http://ws.geonames.org/postalCodeLookupJSON?postalcode=6600&country=AT
"target":"postalCodeLookupJSON",
"parameters":[
{ name:"postalcode", type:"STRING" },
{ name:"country", type:"STRING",optional:true},
{ name:"maxRows", type:"INTEGER", optional:true }, // def: 20
{ name:"charset", type:"STRING",optional:true } // def: utf-8
]
},
"postalCodeSearch":{
"target":"postalCodeSearchJSON",
"parameters":[
{ name:"postalcode", type:"STRING",optional:true}, // one or the other
{ name:"placename", type:"STRING",optional:true }, // one or the other
{ name:"country", type:"STRING",optional:true},
{ name:"style", type:"STRING",optional:true}, // def: MEDIUM
{ name:"maxRows", type:"INTEGER",optional:true}, // def: 20
{ name:"charset", type:"STRING",optional:true} // def: utf-8
]
}
// TODO: implement:
// findNearby,
// findNearbyPlaceName
// findNearbyPostalCodes,
// findNearbyStreets,
// findNearByWeather
// findNearByWikipedia
// findNeareastAddress
// findNearestInterestion
// get
// gtop30
// srtm3
} // end services
}