Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Further cleanup and fixes

  • Loading branch information...
commit 385afdebfaa5dec41d1ce08cae987fedcdc6ccb7 1 parent 3f534ef
@manveru authored
Showing with 255 additions and 171 deletions.
  1. +29 −2 README.textile → README.md
  2. +226 −169 lib/geonames.rb
View
31 README.textile → README.md
@@ -1,11 +1,38 @@
-h1. GeoNames API wrapper
+# GeoNames API wrapper
The GeoNames geographical database covers all countries and contains over eight
million placenames that are available for download free of charge.
http://www.geonames.org/
-h2. This library is licensed under the MIT License
+
+## Dependencies
+
+This library depends on addressable, you can install it with
+`gem install addressable`.
+
+
+## Usage
+
+Instantiate the API and make a query:
+
+ >> api = GeoNames.new
+ >> api.ocean(lat: 0, lng: 0)
+ => {"name"=>"North Atlantic Ocean"}
+
+Please read the documentation of the methods in the GeoNames class for more
+information about the available methods and their arguments.
+
+
+## About
+
+I wrote this library in hopes to improve upon the original geonames library
+written by Adam Wisniewski.
+It's around 1/5 of the code now, and should be easier to read, understand,
+extend, and hack while being closer to the original specification of the API.
+
+
+### This library is licensed under the MIT License
Copyright (c) 2010 Michael Fellinger
View
395 lib/geonames.rb
@@ -17,14 +17,22 @@ class GeoNames
def initialize(options = {})
@options = OPTIONS.merge(options)
@uris = Hash[QUERY.map{|name, args|
- joined = args.flatten.uniq.sort.join(',')
- template = Addressable::Template.new(
- "http://{host}/#{name}JSON?{-join|&|#{joined}}"
- )
+ if args.empty?
+ template = Addressable::Template.new(
+ "http://{host}/#{name}JSON"
+ )
+ else
+ joined = args.flatten.uniq.sort.join(',')
+ template = Addressable::Template.new(
+ "http://{host}/#{name}JSON?{-join|&|#{joined}}"
+ )
+ end
[name, template]
}]
end
+ # Execute query for given +name+ with +parameters+ translated via URI
+ # template expansion.
def query(name, parameters)
default = {host: options[:host]}
default[:username] = options[:username] if options[:username]
@@ -38,6 +46,8 @@ def query(name, parameters)
end
end
+ # Utility method for some queries that return times, we convert them to real
+ # Time instances with proper UTC timezone.
def fix_datetime(hash)
if time = hash['datetime']
zone, format = options.values_at(:timezone, :time_format)
@@ -49,6 +59,8 @@ def fix_datetime(hash)
# Returns a list of recent earthquakes, ordered by magnitude
#
+ # @parse
+ #
# north, south, east, west: coordinates of bounding box
# callback: name of javascript function (optional parameter)
# date: date of earthquakes 'yyyy-MM-dd', optional parameter
@@ -57,7 +69,7 @@ def fix_datetime(hash)
#
# Example:
#
- # GeoNames.earthquakes(north: 44.1, south: -9.9, east: -22.4, west: 55.2)
+ # api.earthquakes(north: 44.1, south: -9.9, east: -22.4, west: 55.2)
def earthquakes(parameters = {})
quakes = query(:earthquakes, parameters)['earthquakes']
quakes.map{|quake| fix_datetime(quake) }
@@ -77,7 +89,7 @@ def earthquakes(parameters = {})
#
# Example:
#
- # GeoNames.astergdem(lat: 50.01, lng: 10.2)
+ # api.astergdem(lat: 50.01, lng: 10.2)
def astergdem(parameters = {})
query(:astergdem, parameters)
end
@@ -95,7 +107,7 @@ def astergdem(parameters = {})
#
# Example:
#
- # GeoNames.gtopo30(lat: 50.01, lng: 10.2)
+ # api.gtopo30(lat: 50.01, lng: 10.2)
def gtopo30(parameters = {})
query(:gtopo30, parameters)
end
@@ -113,7 +125,7 @@ def gtopo30(parameters = {})
#
# Example:
#
- # GeoNames.children(geonameId: 3175395, maxRows: 5)
+ # api.children(geonameId: 3175395, maxRows: 5)
def children(parameters = {})
query(:children, parameters)
end
@@ -129,7 +141,7 @@ def children(parameters = {})
#
# Example:
#
- # GeoNames.hierarchy(geonameId: 2657896)
+ # api.hierarchy(geonameId: 2657896)
def hierarchy(parameters = {})
query(:hierarchy, parameters)
end
@@ -146,7 +158,7 @@ def hierarchy(parameters = {})
#
# Example:
#
- # GeoNames.neighbours(geonameId: 2658434)
+ # api.neighbours(geonameId: 2658434)
def neighbours(parameters = {})
query(:neighbours, parameters)
end
@@ -162,7 +174,7 @@ def neighbours(parameters = {})
#
# Example:
#
- # GeoNames.siblings(geonameId: 3017382)
+ # api.siblings(geonameId: 3017382)
def siblings(parameters = {})
query(:siblings, parameters)['geonames']
end
@@ -183,7 +195,7 @@ def siblings(parameters = {})
#
# Example:
#
- # GeoNames.cities(north: 44.1, south: -9.9, east: -22.4, west: 55.2, lang: 'de')
+ # api.cities(north: 44.1, south: -9.9, east: -22.4, west: 55.2, lang: 'de')
def cities(parameters = {})
query(:cities, parameters)['geonames']
end
@@ -200,7 +212,7 @@ def cities(parameters = {})
#
# Example:
#
- # GeoNames.weather(north: 44.1, south: -9.9, east: -22.4, west: 55.2)
+ # api.weather(north: 44.1, south: -9.9, east: -22.4, west: 55.2)
def weather(parameters = {})
observations = query(:weather, parameters)['weatherObservations']
observations.map{|observation| fix_datetime(observation) }
@@ -216,7 +228,7 @@ def weather(parameters = {})
#
# Example:
#
- # GeoNames.weather_icao(ICAO: 'LSZH')
+ # api.weather_icao(ICAO: 'LSZH')
def weather_icao(parameters = {})
weather = query(:weatherIcao, parameters)['weatherObservation']
fix_datetime(weather)
@@ -231,7 +243,7 @@ def weather_icao(parameters = {})
#
# Example:
#
- # GeoNames.country_info(lang: 'it', country: 'DE')
+ # api.country_info(lang: 'it', country: 'DE')
def country_info(parameters = {})
query(:countryInfo, parameters)["geonames"]
end
@@ -250,7 +262,7 @@ def country_info(parameters = {})
#
# Example:
#
- # GeoNames.country_code(lat: 47.03, lng: 10.2)
+ # api.country_code(lat: 47.03, lng: 10.2)
def country_code(parameters = {})
if parameters[:type].to_s =~ /^xml$/i
query(:countryCode, parameters){|content| return content }
@@ -271,11 +283,11 @@ def country_code(parameters = {})
#
# Example:
#
- # GeoNames.country_subdivision(lat: 47.03, lng: 10.2)
+ # api.country_subdivision(lat: 47.03, lng: 10.2)
#
# # With the parameters 'radius' and 'maxRows' you get the closest
# # subdivisions ordered by distance:
- # GeoNames.country_subdivision(lat: 47.03, lng: 10.2, maxRows: 10, radius: 40)
+ # api.country_subdivision(lat: 47.03, lng: 10.2, maxRows: 10, radius: 40)
def country_subdivision(parameters = {})
query(:countrySubdivision, parameters)
end
@@ -288,7 +300,7 @@ def country_subdivision(parameters = {})
#
# Example:
#
- # GeoNames.ocean(lat: 40.78343, lng: -43.96625)
+ # api.ocean(lat: 40.78343, lng: -43.96625)
def ocean(parameters = {})
query(:ocean, parameters)["ocean"]
end
@@ -302,7 +314,7 @@ def ocean(parameters = {})
#
# Example:
#
- # GeoNames.neighbourhood(lat: 40.78343, lng: -73.96625)
+ # api.neighbourhood(lat: 40.78343, lng: -73.96625)
def neighbourhood(parameters = {})
query(:neighbourhood, parameters)["neighbourhood"]
end
@@ -324,7 +336,7 @@ def neighbourhood(parameters = {})
#
# Example:
#
- # GeoNames.srtm3(lat: 50.01, lng: 10.2)
+ # api.srtm3(lat: 50.01, lng: 10.2)
def srtm3(parameters = {})
query(:srtm3, parameters)
end
@@ -341,7 +353,7 @@ def srtm3(parameters = {})
#
# Example:
#
- # GeoNames.timezone(lat: 47.01, lng: 10.2)
+ # api.timezone(lat: 47.01, lng: 10.2)
def timezone(parameters = {})
query(:timezone, parameters)
end
@@ -356,7 +368,7 @@ def timezone(parameters = {})
#
# Example:
#
- # GeoNames.find_nearby(lat: 47.3, lng: 9)
+ # api.find_nearby(lat: 47.3, lng: 9)
def find_nearby(parameters = {})
query(:findNearby, parameters)
end
@@ -374,7 +386,7 @@ def find_nearby(parameters = {})
#
# Example:
#
- # GeoNames.extended_find_nearby(lat: 47.3, lng: 9)
+ # api.extended_find_nearby(lat: 47.3, lng: 9)
def extended_find_nearby(parameters = {})
raise(NotImplementedError, "XML queries haven't been implemented.")
query(:extendedFindNearby, parameters)
@@ -393,7 +405,7 @@ def extended_find_nearby(parameters = {})
#
# Example:
#
- # GeoNames.find_nearby_place_name(lat: 47.3, lng: 9)
+ # api.find_nearby_place_name(lat: 47.3, lng: 9)
def find_nearby_place_name(parameters = {})
query(:findNearbyPlaceName, parameters)["geonames"]
end
@@ -402,7 +414,8 @@ def find_nearby_place_name(parameters = {})
# List of nearby postalcodes and places for the lat/lng query.
# The result is sorted by distance.
#
- # This service comes in two flavors. You can either pass the lat/long or a postalcode/placename.
+ # This service comes in two flavors. You can either pass the lat/long or a
+ # postalcode/placename.
#
# Parameters:
#
@@ -418,8 +431,8 @@ def find_nearby_place_name(parameters = {})
#
# Example:
#
- # GeoNames.find_nearby_postal_codes(lat: 47, lng: 9)
- # GeoNames.find_nearby_postal_codes(postalcode: 8775, country: 'CH', radius: 10)
+ # api.find_nearby_postal_codes(lat: 47, lng: 9)
+ # api.find_nearby_postal_codes(postalcode: 8775, country: 'CH', radius: 10)
def find_nearby_postal_codes(parameters = {})
query(:findNearbyPostalCodes, parameters)["postalCodes"]
end
@@ -430,44 +443,50 @@ def find_nearby_postal_codes(parameters = {})
# Returns the nearest street segments for the given latitude/longitude, this
# service is only available for the US.
#
- # Parameters : lat,lng;
- # Restriction : this webservice is only available for the US.
- # Example http://ws.geonames.org/findNearbyStreets?lat=37.451&lng=-122.18
- #
- # This service is also available in JSON format :
- # http://ws.geonames.org/findNearbyStreetsJSON?lat=37.451&lng=-122.18
- #
- # Returned Elements :
- # line : line string with lng lat points, points are comma separated
- # mtfcc : MAF/TIGER Feature Class Code
- # name : street name
- # fraddl : from address left
- # fraddr : from address right
- # toaddl : to address left
- # toaddr : to address right
- # the other elments are selfexplaining.
-
- def find_nearby_streets(parameters = {})
- query(:findNearbyStreets, parameters)
+ # @param [Float] latitude Latitude
+ # @param [Float] longitude Longitude
+ #
+ # @return [Array] An Array containing zero or more street segments.
+ #
+ # A street segment has following keys:
+ # "adminCode1": Identifier of state.
+ # "adminCode2": Area code.
+ # "adminName1": Name of state.
+ # "adminName2": Name of province.
+ # "countryCode": Name of country (usually "US")
+ # "distance": Distance of street to given coordinates in km.
+ # "fraddl": From address left.
+ # "fraddr": From address right.
+ # "line": A string with lng/lat points, comma separated.
+ # "mtfcc": MAF/TIGER Feature class code.
+ # "name:" Name of the street.
+ # "postalcode": Postal code of the address.
+ # "toaddl": To address left.
+ # "toaddr": To address right.
+ #
+ # @example
+ # api.find_nearby_streets(37.451, -122.18)
+ def find_nearby_streets(latitude, longitude)
+ [*query(:findNearbyStreets, lat: latitude, lng: longitude)['streetSegment']]
end
QUERY[:findNearbyStreets] = %w[lat lng]
- # Find nearby Streets
- # uses OpenStreetMap http://www.openstreetmap.org/
+ # Find nearby street segments on OpenStreetMap for the given
+ # latitude/longitude.
#
- # Finds the nearest street for a given lat/lng pair.
- # Url : ws.geonames.org/findNearbyStreetsOSM?
- # Parameters : lat,lng;
- # Result : returns the nearest street segments for the given latitude/longitude
- # Example http://ws.geonames.org/findNearbyStreetsOSM?lat=37.451&lng=-122.18
- def find_nearby_streets_osm(parameters = {})
- query(:findNearbyStreetsOSM, parameters)
+ # @param [Float, String] latitude
+ # @param [Float, String] longitude
+ #
+ # @example
+ # api.find_nearby_streets_osm(37.451, -122.18)
+ def find_nearby_streets_osm(latitude, longitude)
+ query(:findNearbyStreetsOSM, lat: latitude, lng: longitude)
end
QUERY[:findNearbyStreetsOSM] = %w[lat lng]
- # Weather Station with most recent weather observation / reverse geocoding
- # needs username
+ # Weather Station with most recent weather observation / reverse geocoding
+ # needs username
#
# Webservice Type : REST
# Url : ws.geonames.org/findNearByWeatherJSON?
@@ -539,50 +558,56 @@ def find_nearest_intersection(parameters = {})
end
QUERY[:findNearestIntersection] = %w[lat lng]
- # Find nearest Intersection
- # # uses OpenStreetMap http://www.openstreetmap.org/
+ # Find nearest street and crossing for a given latitude/longitude pair on
+ # OpenStreetMap.
#
- # Finds the nearest street and the next crossing street for a given lat/lng pair.
- # Url : ws.geonames.org/findNearestIntersectionOSM?
- # Parameters : lat,lng;
- # Result : returns the nearest intersection for the given latitude/longitude
- # Example http://ws.geonames.org/findNearestIntersectionOSM?lat=37.451&lng=-122.18
+ # @param [Float] latitude
+ # @param [Float] longitude
#
- # This service is also available in JSON format :
- # http://ws.geonames.org/findNearestIntersectionOSMJSON?lat=37.451&lng=-122.18
+ # @example
+ # api.find_nearest_intersection_osm(37.451, -122.18)
def find_nearest_intersection_osm(parameters = {})
query(:findNearestIntersectionOSM, parameters)
end
QUERY[:findNearestIntersectionOSM] = %w[lat lng]
- # Postal code country info
+ # Postal code country info
#
- # Webservice Type : REST
- # Url : ws.geonames.org/postalCodeCountryInfo?
- # Result : countries for which postal code geocoding is available.
- # Example : http://ws.geonames.org/postalCodeCountryInfo?
+ # @return [Array] Countries for which postal code geocoding is available.
+ #
+ # @example
+ # api.postal_code_country_info
def postal_code_country_info(parameters = {})
- query(:postalCodeCountryInfo, parameters)
+ query(:postalCodeCountryInfo, {})['geonames']
end
QUERY[:postalCodeCountryInfo] = []
- # Placename lookup with postalcode (JSON)
+ # Placename lookup with postalcode
#
- # Webservice Type : REST /JSON
- # Url : ws.geonames.org/postalCodeLookupJSON?
- # Parameters : postalcode,country ,maxRows (default = 20),callback, charset (default = UTF-8)
- # Result : returns a list of places for the given postalcode in JSON format
- # Example http://ws.geonames.org/postalCodeLookupJSON?postalcode=6600&country=AT
+ #
+ # @param [Hash] parameters
+ # @option parameters [String, Fixnum] :postalcode
+ # @option parameters [String] :country
+ # @option parameters [Fixnum] :maxRows (20)
+ # @option parameters [String] :callback
+ # @option parameters [String] :charset ('UTF-8')
+ #
+ # @return [Array] List of places for the given postalcode.
+ #
+ # @example
+ # api.postal_code_lookup(postalcode: 6600, country: 'AT')
def postal_code_lookup(parameters = {})
query(:postalCodeLookup, parameters)
end
QUERY[:postalCodeLookup] = %w[postalcode country maxRows, callback charset]
- # Postal Code Search
+ # Postal Code Search
+ # Returns a list of postal codes and places for the placename/postalcode query.
+ #
+ # For the US the first returned zip code is determined using zip code area
+ # shapes, the following zip codes are based on the centroid. For all other
+ # supported countries all returned postal codes are based on centroids.
#
- # Url » ws.geonames.org/postalCodeSearch?
- # Result » returns a list of postal codes and places for the placename/postalcode query as xml document
- # For the US the first returned zip code is determined using zip code area shapes, the following zip codes are based on the centroid. For all other supported countries all returned postal codes are based on centroids.
# Parameter Value Description
# postalcode string (postalcode or placename required) postal code
# postalcode_startsWith string the first characters or letters of a postal code
@@ -595,9 +620,9 @@ def postal_code_lookup(parameters = {})
# operator string AND,OR (optional) the operator 'AND' searches for all terms in the placename parameter, the operator 'OR' searches for any term, default = AND
# charset string (optional) default is 'UTF8', defines the encoding used for the document returned by the web service.
# isReduced true or false (optional) default is 'false', when set to 'true' only the UK outer codes are returned. Attention: the default value on the commercial servers is currently set to 'true'. It will be changed later to 'false'.
- # Example http://ws.geonames.org/postalCodeSearch?postalcode=9011&maxRows=10
#
- # This service is also available in JSON format : http://ws.geonames.org/postalCodeSearchJSON?postalcode=9011&maxRows=10
+ # @example
+ # api.postal_code_search(postalcode: 9011, maxRows: 10)
def postal_code_search(parameters = {})
query(:postalCodeSearch, parameters)
end
@@ -606,72 +631,92 @@ def postal_code_search(parameters = {})
maxRows style operator charset isReduced
]
- # GeoNames Search Webservice
- #
- #
- # Webservice Description
- #
- # Url » ws.geonames.org/search?
- # Result » returns the names found for the searchterm as xml or json document, the search is using an AND operator
- #
- # Parameter Value Description
- # q string (q,name or name_equals required) search over all attributes of a place : place name, country name, continent, admin codes,... (Important:urlencoded utf8)
- # name string (q,name or name_equals required) place name only(Important:urlencoded utf8)
- # name_equals string (q,name or name_equals required) exact place name
- # name_startsWith string (optional) place name starts with given characters
- # maxRows integer (optional) the maximal number of rows in the document returned by the service. Default is 100, the maximal allowed value is 1000.
- # startRow integer (optional) Used for paging results. If you want to get results 30 to 40, use startRow=30 and maxRows=10. Default is 0.
- # country string : country code, ISO-3166 (optional) Default is all countries. The country parameter may occur more then once, example: country=FR&country=GP
- # countryBias string (option) records from the countryBias are listed first
- # continentCode string : continent code : AF,AS,EU,NA,OC,SA,AN (optional) restricts the search for toponym of the given continent.
- # adminCode1, adminCode2, adminCode3 string : admin code (optional) code of administrative subdivision
- # featureClass character A,H,L,P,R,S,T,U,V (optional) featureclass(es) (default= all feature classes); this parameter may occur more then once, example: featureClass=P&featureClass=A
- # featureCode string (optional) featurecode(s) (default= all feature codes); this parameter may occur more then once, example: featureCode=PPLC&featureCode=PPLX
- # lang string ISO-636 2-letter language code; en,de,fr,it,es,... (optional) place name and country name will be returned in the specified language. Default is English. Feature classes and codes are only available in English and Bulgarian. Any help in translating is welcome.
- # type string xml,json,rdf the format type of the returned document, default = xml
- # style string SHORT,MEDIUM,LONG,FULL (optional) verbosity of returned xml document, default = MEDIUM
- # isNameRequired boolean (optional) At least one of the search term needs to be part of the place name. Example : A normal seach for Berlin will return all places within the state of Berlin. If we only want to find places with 'Berlin' in the name we se the parameter isNameRequired to 'true'. The difference to the name_equals parameter is that this will allow searches for 'Berlin, Germany' as only one search term needs to be part of the name.
- # tag string (optional) search for toponyms tagged with the specified tag
- # operator string (optional) default is 'AND', with the operator 'OR' not all search terms need to be matched by the response
- # charset string (optional) default is 'UTF8', defines the encoding used for the document returned by the web service.
- #
- #
- # Examples
- #
- # XML
- # Example 1 : http://ws.geonames.org/search?q=london&maxRows=10
- # Example 2 : http://ws.geonames.org/search?q=london&maxRows=10&style=LONG&lang=es
- #
- #
- # JSON
- # http://ws.geonames.org/searchJSON?q=london&maxRows=10
- #
- # JSON is easier to use in Javascript then XML, as a browser security feature will no allow you to call an xml service from an other domain. A simple example using the json service on googlemaps is here
- #
- # 'name' and 'toponymName'
- # The response returns two name attributes. The 'name' attribute is a localized name, the preferred name in the language passed in the optional 'lang' parameter or the name that triggered the response in a 'startWith' search. The attribute 'toponymName' is the main name of the toponym as displayed on the google maps interface page or in the geoname file in the download. The 'name' attribute is derived from the alternate names.
- #
- #
- # Reverse Geocoding
- # Reverse geocoding is the process of finding a place name for a given latitude and longitude. GeoNames has a wide range of reverse geocoding webservices.
- #
- #
- # RDF - Semantic Web
- # http://ws.geonames.org/search?q=london&maxRows=10&type=rdf
- #
- # With the parameter type=rdf the search service returns the result in RDF format defined by the GeoNames Semantic Web Ontology.
+ # Returns the names found for the searchterm as xml, json, or rdf document,
+ # the search is using the AND operator.
+ #
+ # @param [Hash] parameters
+ # @option parameters [String] :q
+ # search over all attributes of a place, place name, country name,
+ # continent, admin codes, ...
+ # @option parameters [String] :name
+ # place name only
+ # @option parameters [String] :name_equals
+ # exact place name
+ # @option parameters [String] :name_startsWith
+ # place name starts with given characters
+ # @option parameters [Fixnum] :maxRows (100)
+ # maximum number of results, up to 1000
+ # @option parameters [Fixnum] :startRow (0)
+ # used for paging results.
+ # @option parameters [String, Array] :country
+ # Country code, ISO-3166 (optional). Default is all countries. May have
+ # more than one country as an Array.
+ # @option parameters [String] :countryBias
+ # records from this country will be listed first.
+ # @option parameters [String] :continentCode
+ # AF,AS,EU,NA,OC,SA,AN (optional) restricts the search to the given
+ # continent.
+ # @option parameters [String] :adminCode1
+ # code of administrative subdivision
+ # @option parameters [String] :adminCode2
+ # code of administrative subdivision
+ # @option parameters [String] :adminCode3
+ # code of administrative subdivision
+ # @option parameters [String, Array] :featureClass
+ # one or more feature class codes, explanation at
+ # http://forum.geonames.org/gforum/posts/list/130.page
+ # @option parameters [String, Array] :featureCode
+ # one or more feature class codes, explanation at
+ # http://forum.geonames.org/gforum/posts/list/130.page
+ # @option parameters [String] :lang ('en')
+ # ISO-636 2-letter language code; en, de, fr, it, es, ...
+ # place names and country names will be returned in the specified language.
+ # Feature classes and codes are only available in English and Bulgarian.
+ # @option parameters [String] :type ('json')
+ # format of returned document.
+ # @option parameters [String] :style ('MEDIUM')
+ # verbosity of returned document.
+ # @option parameters [String] :isNameRequired (false)
+ # At least one of the search term needs to be part of the place name.
+ # Example: A normal seach for Berlin will return all places within the
+ # state of Berlin. If we only want to find places with 'Berlin' in the name
+ # we se the parameter isNameRequired to `true`. The difference to the
+ # :name_equals parameter is that this will allow searches for 'Berlin,
+ # Germany' as only one search term needs to be part of the name.
+ # @option parameters [String] :tag
+ # search for toponyms tagged with the given tag.
+ # @option parameters [String] :charset ('UTF8')
+ # encoding of returned document, this wrapper only handles UTF8 for now.
+ #
+ # @example
+ # api.search(q: 'london', maxRows: 10)
+ # api.search(q: 'london', maxRows: 10, type: 'rdf')
+ # api.search(q: 'skiresort')
+ # api.search(q: 'tags:skiresort')
+ # api.search(q: 'tags:skiresort@marc')
+ #
+ # With the parameter `type: 'rdf'` the search service returns the result in RDF
+ # format defined by the GeoNames Semantic Web Ontology.
#
#
# Tags
- # GeoNames is using a simple tagging system. Every user can tag places. In contrast to the feature codes and feature classes which are one-dimensional (a place name can only have one feature code) several tags can be used for each place name. It is an additional categorization mechanism where the simple classification with feature codes is not sufficient.
- #
- # I have tagged a place with the tag 'skiresort'. You can search for tags with the search : http://www.geonames.org/search.html?q=skiresort
- # If you only want to search for a tag and not for other occurences of the term (in case you tag something with 'spain' for example), then you add the attribute 'tags:' to the search term : http://www.geonames.org/search.html?q=tags:skiresort
- #
- # And if you want to search for tags of a particular user (or your own) then you append '@username' to the tag. Like this :
- # http://www.geonames.org/search.html?q=tags:skiresort@marc
+ # GeoNames is using a simple tagging system. Every user can tag places. In
+ # contrast to the feature codes and feature classes which are one-dimensional
+ # (a place name can only have one feature code) several tags can be used for
+ # each place name. It is an additional categorization mechanism where the
+ # simple classification with feature codes is not sufficient.
+ #
+ # I have tagged a place with the tag 'skiresort'. You can search for tags
+ # with the search: `api.search(q: 'skiresort')` If you only want to search
+ # for a tag and not for other occurences of the term (in case you tag
+ # something with 'spain' for example), then you add the attribute 'tags:' to
+ # the search term: `api.search(q: 'tags:skiresort')`
+ #
+ # And if you want to search for tags of a particular user (or your own) then
+ # you append '@username' to the tag. Like this:
+ # `api.search(q: 'tags:skiresort@marc')
def search(parameters = {})
- query(:search, parameters)
+ query(:search, parameters)['geonames']
end
QUERY[:search] = %w[
q name name_equals name_startsWith maxRows startRow country countryBias
@@ -679,34 +724,46 @@ def search(parameters = {})
lang type style isNameRequired tag operator charset
]
- # Wikipedia Articles in Bounding Box
+ # Wikipedia articles within a bounding box
+ #
+ # @param [Hash] parameters
+ # @option parameters [Float] :south Southern latitude
+ # @option parameters [Float] :north Northern latitude
+ # @option parameters [Float] :east Eastern longitude
+ # @option parameters [Float] :west Western longitude
+ # @option parameters [String] :lang ('en') language
+ # @option parameters [Fixnum] :maxRows ('10') maximum number of results
+ #
+ # @return [Array] The Wikipedia entries found.
#
- # Webservice Type : XML or JSON
- # Url : ws.geonames.org/wikipediaBoundingBox?
- # ws.geonames.org/wikipediaBoundingBoxJSON?
- # Parameters : south,north,east, west : coordinates of bounding box
- # lang : language either 'de' or 'en' (default = en)
- # maxRows : maximal number of rows returned (default = 10)
- # Result : returns the wikipedia entries within the bounding box as xml document
- # Example http://ws.geonames.org/wikipediaBoundingBox?north=44.1&south=-9.9&east=-22.4&west=55.2
+ # @example
+ # api.wikipedia_bounding_box(north: 44.1, south: -9.9, east: -22.4, west: 55.2)
def wikipedia_bounding_box(parameters = {})
- query(:wikipediaBoundingBox, parameters)
+ [*query(:wikipediaBoundingBox, parameters)['geonames']]
end
QUERY[:wikipediaBoundingBox] = %w[south north east west lang maxRows]
- # Wikipedia Fulltext Search
- #
- # Webservice Type : XML or JSON
- # Url : ws.geonames.org/wikipediaSearch?
- # ws.geonames.org/wikipediaSearchJSON?
- # Parameters : q : place name (urlencoded utf8)
- # title : search in the wikipedia title (optional)
- # lang : language either 'de' or 'en' (default = en)
- # maxRows : maximal number of rows returned (default = 10)
- # Result : returns the wikipedia entries found for the searchterm as xml document
- # Example http://ws.geonames.org/wikipediaSearch?q=london&maxRows=10
+ # Wikipedia Fulltext Search
+ #
+ # @param [Hash] parameters
+ # @option parameters [String] :q
+ # place name
+ # @option parameters [String] :title (false)
+ # search in the wikipedia title (optional, true/false)
+ # @option parameters [String] :lang ('en')
+ # language
+ # @option parameters [Fixnum] :maxRows (10)
+ # maximum number of results
+ #
+ # @return [Array] The Wikipedia entries found.
+ #
+ # @example
+ # api.wikipedia_search(q: 'London', maxRows: 10, lang: 'en', title: true)
+ # api.wikipedia_search(q: '秋葉原')
def wikipedia_search(parameters = {})
- query(:wikipediaSearch, parameters)
+ params = parameters.dup
+ params[:title] = '' if params[:title] # weird?
+ [*query(:wikipediaSearch, params)['geonames']]
end
QUERY[:wikipediaSearch] = %w[q title lang maxRows]
end
Please sign in to comment.
Something went wrong with that request. Please try again.