Versions Compared

Old Version 1

changes.mady.by.user Former user

Saved on

compared with

New Version Current

changes.mady.by.user Former user

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Table of Contents
maxLevel3
typeflat

...

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

1Working with Postal Codes in GeoNameslistNearbyPostalCodes

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

1Working with Postal Codes in GeoNameslistPlacesForPostalCode

Retrieves a list of places for the given postal code.

1Working with Postal Codes in GeoNamespostalCodeSearchRetrieves 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.

Anchor
listNearbyPostalCodes
listNearbyPostalCodes
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.

Code Block
languagexml
titlelistNearbyPostalCodes 
<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.
  
Anchor
request
request
Sample request

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

Code Block
languagexml
titleSample 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

Anchor
listPlacesForPostalCode
listPlacesForPostalCode
Retrieving a list of places for the given postal code 

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

Code Block
languagexml
titlelistPlacesForPostalCode
<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.
  
Anchor
request
request
Sample request

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

Code Block
languagexml
titleSample 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

Anchor
postalCodeSearch
postalCodeSearch
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.

Code Block
languagexml
titlepostalCodeSearch 
<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.
  
Anchor
request
request
Sample request

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

Code Block
languagexml
titleSample 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

Anchor
sampleconfiguration
sampleconfiguration
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.

Code Block
languagexml
titleSample 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>