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 Postal Codes in GeoNames

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

Overview

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

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

OperationDescription

listNearbyPostalCodes

Retrieving a list of postal codes and places for the latitude/longitude query.

listPlacesForPostalCode

Retrieves a list of places for the given postal code.

postalCodeSearchRetrieves a list of postal codes and places for the place name/postal code query.

Operation details

This section provides further details on the operations related to postal codes.

Retrieving a list of postal codes and places for the latitude/longitude query

The listNearbyPostalCodes operation retrieves a list of postal codes and places for the latitude/longitude query.

listNearbyPostalCodes 
<geonames.listNearbyPostalCodes>
    <localCountry>{$ctx:localCountry}</localCountry>
    <postalCode>{$ctx:postalCode}</postalCode>
    <style>{$ctx:style}</style>
    <responseType>{$ctx:responseType}</responseType>
    <maxRows>{$ctx:maxRows}</maxRows>
    <placeName>{$ctx:placeName}</placeName>
    <radius>{$ctx:radius}</radius>
    <longitude>{$ctx:longitude}</longitude>
    <latitude>{$ctx:latitude}</latitude>
	<country>{$ctx:country}</country>
</geonames.listNearbyPostalCodes>
Properties
  • localCountry: The local country values.
  • postalCode: The postal code to determine the nearby postal codes.
  • style: The verbosity of the returned XML document, default = MEDIUM.
  • responseType: The response type to get the response of the listNearbyPostalCodes.
  • maxRows: The maximal number of rows in the document returned by the service. Default is 10.
  • placeName: All fields: place name,postal code, country, admin name.
  • radius: The radius which is used to buffer in KM for closest timezone in coastal areas
  • longitude: The longitude to retrieve nearby postal codes.
  • latitude: The latitude to retrieve nearby postal codes.
  • country: Default is all countries. The country parameter may occur more than once,country=FR,country=GP.
   Sample request

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

Sample Request for listNearbyPostalCodes 
{
	"apiUrl" : "http://api.geonames.org",
	"username" : "yasasi",
	"responseType" :"json",
	"placeName": "Ettelbruck",
	"maxRows":"2",
	"localCountry":"FR",
	"postalCode":"9011",
	"style":"MEDIUM",
	"radius":"12",
	"longitude":"10.2",
	"latitude":"47.01",
	"country":"DE"
}
Related GeoNames documentation

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

Retrieving a list of places for the given postal code 

The listPlacesForPostalCode operation retrieves a list of places for the given postal code.

listPlacesForPostalCode
<geonames.listPlacesForPostalCode>
    <postalCode>{$ctx:postalCode}</postalCode>
    <charset>{$ctx:charset}</charset>
    <callback>{$ctx:callback}</callback>
    <maxRows>{$ctx:maxRows}</maxRows>
	<country>{$ctx:country}</country>
</geonames.listPlacesForPostalCode>
Properties
  • postalCode: The postal code of a particular place.
  • charset: The default is 'UTF8', defines the encoding used for the document returned by the web service.
  • callback: The callback value of the listPlacesForPostalcode function.
  • maxRows: The maximal number of rows in the document returned by the service.
  • country: The country belonging to the specified place.
   Sample request

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

Sample Request for listPlacesForPostalCode 
{
	"apiUrl" : "http://api.geonames.org",
	"username" : "yasasi",
	"postalCode": "9011",
	"maxRows":"2",
	"charset":"UTF-8",
	"callback":"callbackFunction",
	"country":"DE"
}
Related GeoNames documentation

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

Retrieving a list of postal codes and places for the place name/postal code query

The postalCodeSearch operation retrieves a list of postal codes and places for the place name/postal code query.

postalCodeSearch 
<geonames.postalCodeSearch>
    <isReduced>{$ctx:isReduced}</isReduced>
    <charset>{$ctx:charset}</charset>
    <placeName>{$ctx:placeName}</placeName>
    <north>{$ctx:north}</north>
    <countryBias>{$ctx:countryBias}</countryBias>
    <operator>{$ctx:operator}</operator>
    <country>{$ctx:country}</country>
    <placeNameStartsWith>{$ctx:placeNameStartsWith}</placeNameStartsWith>
    <postalCode>{$ctx:postalCode}</postalCode>
    <postalCodeStartsWith>{$ctx:postalCodeStartsWith}</postalCodeStartsWith>
    <style>{$ctx:style}</style>
    <responseType>{$ctx:responseType}</responseType>
    <maxRows>{$ctx:maxRows}</maxRows>
    <south>{$ctx:south}</south>
    <east>{$ctx:east}</east>
	<west>{$ctx:west}</west>
</geonames.postalCodeSearch>
Properties
  • isReduced: The 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'.
  • charset: The default is 'UTF8', defines the encoding used for the document returned by the web service.
  • placeName: All fields : place name,postal code, country, admin name.
  • north: The bounding box, only features within the box are returned.
  • countryBias: Records from the countryBias are listed first.
  • operator: The the operator 'AND' searches for all terms in the placename parameter, the operator 'OR' searches for any term, default = AND.
  • country: Default is all countries. The country parameter may occur more than once,country=FR,country=GP.
  • placeNameStartsWith: The first characters of a place name.
  • postalCode: The postal code to search.
  • postalCodeStartsWith: The first characters or letters of a postal code.
  • style: The verbosity of the returned XML document, default = MEDIUM.
  • responseType: The responseType of the response of the postalCodeSearch method.
  • maxRows: The maximal number of rows in the document returned by the service. Default is 10.
  • south: The bounding box, only features within the box are returned.
  • east: The bounding box, only features within the box are returned.
  • west: The bounding box, only features within the box are returned.
   Sample request

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

Sample Request for postalCodeSearch 
{
	"apiUrl" : "http://api.geonames.org",
	"username" : "yasasi",
	"responseType" : "xml",
	"placeName": "Ettelbruck",
	"maxRows":"2",
	"postalCode":"9011",
	"isReduced":"true",
	"charset":"UTF-8",
	"countryBias":"FR",
	"operator":"AND",
	"country":"DE",
	"placeNameStartsWith":"Ette",
	"postalCodeStartsWith":"90",
	"style":"MEDIUM",
	"north" : "44.1",
	"south" : "9.9",
	"east" : "22.4",
	"west" : "55.2"
}
Related GeoNames documentation

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

Sample configuration

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

Sample Proxy
<?xml version="1.0" encoding="UTF-8"?>
	<proxy xmlns="http://ws.apache.org/ns/synapse" name="geonames_listNearbyPostalCodes" transports="https,http" statistics="disable" trace="disable" startOnLoad="true">
	 <target>
	 <inSequence onError="faultHandlerSeq">
      <property name="username" expression="json-eval($.username)"/>
      <property name="apiUrl" expression="json-eval($.apiUrl)"/>
      <property name="localCountry" expression="json-eval($.localCountry)"/>
      <property name="postalCode" expression="json-eval($.postalCode)"/>
      <property name="style" expression="json-eval($.style)"/>
      <property name="responseType" expression="json-eval($.responseType)"/>
      <property name="maxRows" expression="json-eval($.maxRows)"/>
      <property name="placeName" expression="json-eval($.placeName)"/>
      <property name="radius" expression="json-eval($.radius)"/>
      <property name="longitude" expression="json-eval($.longitude)"/>
      <property name="latitude" expression="json-eval($.latitude)"/>
      <property name="country" expression="json-eval($.country)"/>
      <geonames.init>
         <username>{$ctx:username}</username>
         <apiUrl>{$ctx:apiUrl}</apiUrl>
      </geonames.init>
      <geonames.listNearbyPostalCodes>
         <localCountry>{$ctx:localCountry}</localCountry>
         <postalCode>{$ctx:postalCode}</postalCode>
         <style>{$ctx:style}</style>
         <responseType>{$ctx:responseType}</responseType>
         <maxRows>{$ctx:maxRows}</maxRows>
         <placeName>{$ctx:placeName}</placeName>
         <radius>{$ctx:radius}</radius>
         <longitude>{$ctx:longitude}</longitude>
         <latitude>{$ctx:latitude}</latitude>
         <country>{$ctx:country}</country>
      </geonames.listNearbyPostalCodes>
	   <respond/>
	 </inSequence>
	  <outSequence>
	   <send/>
	  </outSequence>
	 </target>
   <description/>
  </proxy>