This site contains the documentation that is relevant to older WSO2 product versions and offerings.
For the latest WSO2 documentation, visit https://wso2.com/documentation/.

Working with General methods in GeoNames

Owned by Former user (Deleted)
Last updated: Jan 08, 2016
6 min read

Overview

The following operations allow you to work with general methods. Click an operation name to see details on how to use it.

For a sample proxy service that illustrates how to work with general methods, see Sample configuration. 

OperationDescription

getNearByPointsOfInterestOSM

Finds the nearest points of interests for a given latitude/longitude pair.

getNearestIntersectionOSM

Finds the nearest street and the next crossing street for a given latitude/longitude pair.

getNeighbourhoodRetrieves the neighbourhood for US cities. 
getTimezoneRetrieves the timezone at the latitude/longitude with gmt offset (1. January) and dst offset (1. July).
listCitiesAndPlaceNamesRetrieves a list of cities and place names in the bounding box, ordered by relevancy (capital/population).
searchRetrieves the names found for the search term as a XML or JSON document.

Operation details

This section provides further details on the operations related to general methods.

Finding the nearest points of interests for a given latitude/longitude pair

The getNearByPointsOfInterestOSM operation finds the nearest points of interests for a given latitude/longitude pair.

getNearByPointsOfInterestOSM 
<geonames.getNearByPointsOfInterestOSM>
    <longitude>{$ctx:longitude}</longitude>
    <latitude>{$ctx:latitude}</latitude>
    <responseType>{$ctx:responseType}</responseType>
    <maxRows>{$ctx:maxRows}</maxRows>
	<radius>{$ctx:radius}</radius>
</geonames.getNearByPointsOfInterestOSM>
Properties
  • longitude: The longitude value for the point.
  • latitude: The latitude value for the point.
  • responseType: The response type of the method.
  • maxRows: Max rows returned.
  • radius: The radius from the latitude/longitude point.
   Sample request

Following is a sample REST/JSON request that can be handled by the getNearByPointsOfInterestOSM operation.

Sample Request for getNearByPointsOfInterestOSM 
{
  "apiUrl": "http://api.geonames.org",
  "username": "darkenmac",
  "longitude": "-122.18",
  "latitude": "37.451",
  "responseType": "json",
  "maxRows": "1",
  "radius": ".1"
}
Related GeoNames documentation

http://www.geonames.org/maps/osm-reverse-geocoder.html#findNearbyPOIsOSM

Finding the nearest street and the next crossing street for a given latitude/longitude pair

The getNearestIntersectionOSM operation finds the nearest street and the next crossing street for a given latitude/longitude pair.

getNearestIntersectionOSM 
<geonames.getNearestIntersectionOSM>
    <longitude>{$ctx:longitude}</longitude>
    <latitude>{$ctx:latitude}</latitude>
    <responseType>{$ctx:responseType}</responseType>
    <maxRows>{$ctx:maxRows}</maxRows>
	<radius>{$ctx:radius}</radius>
</geonames.getNearestIntersectionOSM>
Properties
  • longitude: The longitude value for the point.
  • latitude: The latitude value for the point.
  • responseType: The response type of the method.
  • maxRows: Max rows returned.
  • radius: The radius from the latitude/longitude point.
   Sample request

Following is a sample REST/JSON request that can be handled by the getNearestIntersectionOSM operation.

Sample Request for getNearestIntersectionOSM 
{
  "apiUrl": "http://api.geonames.org",
  "username": "darkenmac",
  "longitude": "-122.18",
  "latitude": "37.451",
  "responseType": "json",
  "maxRows": "1",
  "radius": ".5"
}
Related GeoNames documentation

http://www.geonames.org/maps/osm-reverse-geocoder.html#findNearestIntersectionOSM

Retrieving the neighbourhood for US cities

The getNeighbourhood operation retrieves the neighbourhood for US cities.

getNeighbourhood 
<geonames.getNeighbourhood>
    <responseType>{$ctx:responseType}</responseType>
    <longitude>{$ctx:longitude}</longitude>
	<latitude>{$ctx:latitude}</latitude>
</geonames.getNeighbourhood>
Properties
  • responseType: The responseType of the getNeighbourhood response.
  • longitude: The longitude value to get the neighourhood details.
  • latitude: The latitude value to get the neighourhood details.
   Sample request

Following is a sample REST/JSON request that can be handled by the getNeighbourhood operation.

Sample Request for getNeighbourhood 
{
	"apiUrl" : "http://api.geonames.org",
	"username" : "yasasi",
	"responseType" : "json",
	"longitude" : "10.2",
	"latitude" : "47.01"
}
Related GeoNames documentation

http://www.geonames.org/export/web-services.html#neighbourhood

Retrieving the timezone at the latitude/longitude 

The getTimezone operation retrieves the timezone at the latitude/longitude with gmt offset (1. January) and dst offset (1. July).

getTimezone 
<geonames.getTimezone>
    <responseType>{$ctx:responseType}</responseType>
    <date>{$ctx:date}</date>
    <radius>{$ctx:radius}</radius>
    <longitude>{$ctx:longitude}</longitude>
    <language>{$ctx:language}</language>
	<latitude>{$ctx:latitude}</latitude>
</geonames.getTimezone>
Properties
  • responseType: The type of the response of getTimeZone method.
  • date: The date to which the timezone is retrieved.
  • radius: The radius which is used to buffer in KM for the closest timezone in coastal areas.
  • longitude: The longitude to which the time zone is retrieved.
  • language: The language of the country to in order to identify the country.
  • latitude: The latitude to which the time zone is retrieved.
   Sample request

Following is a sample REST/JSON request that can be handled by the getTimezone operation.

Sample Request for getTimezone 
{
	"apiUrl" : "http://api.geonames.org",
	"username" : "yasasi",
	"responseType" : "xml",
	"longitude" : "10.2",
	"latitude" : "47.01",
	"date":"2015-12-07 13:20",
	"radius":"1",
	"language":"DE"
}
Related GeoNames documentation

http://www.geonames.org/export/web-services.html#timezone

Retrieving a list of cities and place names

The listCitiesAndPlaceNames operation retrieves a list of cities and place names in the bounding box, ordered by relevancy (capital/population).

listCitiesAndPlaceNames 
<geonames.listCitiesAndPlaceNames>
    <responseType>{$ctx:responseType}</responseType>
    <north>{$ctx:north}</north>
    <south>{$ctx:south}</south>
    <east>{$ctx:east}</east>
    <west>{$ctx:west}</west>
    <callback>{$ctx:callback}</callback>
    <language>{$ctx:language}</language>
	<maxRows>{$ctx:maxRows}</maxRows>
</geonames.listCitiesAndPlaceNames>
Properties
  • responseType: The response type of the method.
  • north: The north coordinates of the bounding box.
  • south: The south coordinates of the bounding box.
  • east: The east coordinates of the bounding box.
  • west: The west coordinates of the bounding box.
  • callback: The name of JavaScript function.
  • language: The language of place names and Wikipedia URLs.
  • maxRows: Max rows returned.
   Sample request

Following is a sample REST/JSON request that can be handled by the listCitiesAndPlaceNames operation.

Sample Request for listCitiesAndPlaceNames 
{
  "apiUrl": "http://api.geonames.org",
  "username": "darkenmac",
  "responseType": "json",
  "north": "44.1",
  "south": "-9.9",
  "east": "-22.4",
  "west": "55.2",
  "callback": "func",
  "language": "ko",
  "maxRows": "2"
}
Related GeoNames documentation

http://www.geonames.org/export/JSON-webservices.html#citiesJSON

Retrieving the names found for the search term

The search operation retrieves the names found for the search term as a XML or JSON document.

search 
<geonames.search>
    <query>{$ctx:query}</query>
    <name>{$ctx:name}</name>
    <nameEquals>{$ctx:nameEquals}</nameEquals>
    <nameStartsWith>{$ctx:nameStartsWith}</nameStartsWith>
    <maxRows>{$ctx:maxRows}</maxRows>
    <startRow>{$ctx:startRow}</startRow>
    <countries>{$ctx:countries}</countries>
    <countryBias>{$ctx:countryBias}</countryBias>
    <continentCode>{$ctx:continentCode}</continentCode>
    <adminCode1>{$ctx:adminCode1}</adminCode1>
    <adminCode2>{$ctx:adminCode2}</adminCode2>
    <adminCode3>{$ctx:adminCode3}</adminCode3>
    <featureClasses>{$ctx:featureClasses}</featureClasses>
    <featureCodes>{$ctx:featureCodes}</featureCodes>
    <cities>{$ctx:cities}</cities>
    <language>{$ctx:language}</language>
    <documentReturnType>{$ctx:documentReturnType}</documentReturnType>
    <style>{$ctx:style}</style>
    <isNameRequired>{$ctx:isNameRequired}</isNameRequired>
    <tag>{$ctx:tag}</tag>
    <operator>{$ctx:operator}</operator>
    <charset>{$ctx:charset}</charset>
    <fuzzy>{$ctx:fuzzy}</fuzzy>
    <east>{$ctx:east}</east>
    <west>{$ctx:west}</west>
    <north>{$ctx:north}</north>
    <south>{$ctx:south}</south>
    <searchLanguage>{$ctx:searchLanguage}</searchLanguage>
    <orderBy>{$ctx:orderBy}</orderBy>
	<responseType>{$ctx:responseType}</responseType>
</geonames.search>
Properties
  • query: The query to search over all attributes of a place.
  • name: The place name.
  • nameEquals: The exact place name.
  • nameStartsWith: The place name starts with given characters.
  • maxRows: The maximal number of rows in the document returned by the service.
  • startRow: The starting row for the result.
  • countries: The country codes to filter the results.
  • countryBias: The two letter country code to filter the results.
  • continentCode: The continent code to filter the results.
  • adminCode1: The code of the administrative subdivision.
  • adminCode2: The code of the administrative subdivision.
  • adminCode3: The code of the administrative subdivision.
  • featureClasses: The feature classes.
  • featureCodes: The feature codes.
  • cities: The city population category.
  • language: The language which place name and country name will be returned.
  • documentReturnType: The format type of the returned document.
  • style: The verbosity of returned XML document.
  • isNameRequired: Value to restrict at least one of the search term needs to be part of the place name.
  • tag: Search for toponyms tagged with the specified tag.
  • operator: The operator to filter the result.
  • charset: The encoding used for the document returned.
  • fuzzy: Defines the fuzziness of the search terms.
  • east: The east value for bounding box.
  • west: The west value for bounding box.
  • north: The north value for bounding box.
  • south: The south value for bounding box.
  • searchLanguage: The search will only consider names in the specified language.
  • orderBy: The value to sort the result.
  • responseType: The response type of the method.
   Sample request

Following is a sample REST/JSON request that can be handled by the search operation.

Sample Request for search 
{
  "apiUrl": "http://api.geonames.org",
  "username": "darkenmac",
  "query": "London",
  "name": "Noank",
  "nameEquals": "Noank Elementary School",
  "nameStartsWith": "N",
  "maxRows": "7",
  "startRow": "0",
  "countries": ["US","UK"],
  "countryBias": "UK",
  "continentCode": "NA",
  "adminCode1": "CT",
  "adminCode2": "011",
  "adminCode3": "01",
  "featureClasses": ["A"],
  "featureCodes": ["PPLC"],
  "cities": "cities1000",
  "language": "en",
  "documentReturnType": "xml",
  "style": "FULL",
  "isNameRequired": "false",
  "tag": "Tag2",
  "operator": "AND",
  "charset": "UTF8",
  "fuzzy": "1",
  "east": "-22.4",
  "west": "11.2",
  "north": "44.1",
  "south": "-9.9",
  "searchLanguage": "en",
  "orderBy": "population",
  "responseType": "json"
}
Related GeoNames documentation

http://www.geonames.org/export/geonames-search.html

Sample configuration

Following is a sample proxy service that illustrates how to connect to GeoNames with the init operation and use the getNearByPointsOfInterestOSM operation. The sample request for this proxy can be found in the getNearByPointsOfInterestOSM sample request.

Sample Proxy
<proxy xmlns="http://ws.apache.org/ns/synapse" name="geonames_getNearByPointsOfInterestOSM" transports="https,http"
   statistics="disable" trace="disable" startOnLoad="true">
   <target>
      <inSequence onError="faultHandlerSeq">
         <property name="apiUrl" expression="json-eval($.apiUrl)" />
         <property name="username" expression="json-eval($.username)" />
         <property name="longitude" expression="json-eval($.longitude)" />
         <property name="latitude" expression="json-eval($.latitude)" />
         <property name="responseType" expression="json-eval($.responseType)" />
         <property name="maxRows" expression="json-eval($.maxRows)" />
         <property name="radius" expression="json-eval($.radius)" />
         <geonames.init>
            <apiUrl>{$ctx:apiUrl}</apiUrl>
            <username>{$ctx:username}</username>
         </geonames.init>
         <geonames.getNearByPointsOfInterestOSM>
            <longitude>{$ctx:longitude}</longitude>
            <latitude>{$ctx:latitude}</latitude>
            <responseType>{$ctx:responseType}</responseType>
            <maxRows>{$ctx:maxRows}</maxRows>
            <radius>{$ctx:radius}</radius>
         </geonames.getNearByPointsOfInterestOSM>
         <respond />
      </inSequence>
      <outSequence>
         <send />
      </outSequence>
   </target>
   <description />
</proxy>