analytics/webcontent/dojo16/dojox/rpc/SMDLibrary/geonames.smd

{

	// 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
}