1Working with General methods in GeoNames

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.

Operation	Description
1Working with General methods in GeoNames	Finds the nearest points of interests for a given latitude/longitude pair.
1Working with General methods in GeoNames	Finds the nearest street and the next crossing street for a given latitude/longitude pair.
1Working with General methods in GeoNames	Retrieves the neighbourhood for US cities.
1Working with General methods in GeoNames	Retrieves the timezone at the latitude/longitude with gmt offset (1. January) and dst offset (1. July).
1Working with General methods in GeoNames	Retrieves a list of cities and place names in the bounding box, ordered by relevancy (capital/population).
1Working with General methods in GeoNames	Retrieves 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"
}

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

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

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

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

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

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>

Overview

Operation details

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

Properties

Sample request

Related GeoNames documentation

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

Properties

Sample request

Related GeoNames documentation

Retrieving the neighbourhood for US cities

Properties

Sample request

Related GeoNames documentation

Retrieving the timezone at the latitude/longitude

Properties

Sample request

Related GeoNames documentation

Retrieving a list of cities and place names

Properties

Sample request

Related GeoNames documentation

Retrieving the names found for the search term

Properties

Sample request

Related GeoNames documentation

Sample configuration