FAO home page
Contact References Search in FAO Français Español
About Climpag Related links
Climpag home page
Global climate grids
Climate data
Climate maps
Spatial interpolation
Methods and tools
 
Spatial interpolation Web LocClim Interoperability
Web LocClim: Local Monthly Climate Estimator

| Web LocClim | More information on LocClim | Using Web LocClim |

Introduction
Beside allowing users to get climatic data through their browsers, the LocClim web site allows other servers to perform interoperability transactions: other servers can directly query the LocClim service to get climate data that they can process for their own purposes.

This documents describes how to perform interoperability transactions with the LocClim web site; it first presents the transaction protocol, and describe the request and the response format. Then, it provides two examples of transactions. Finally, it presents the Java code of a client that connects to the LocClim web site and request some climatic data.

Transaction
The protocol used to get climate data is the HTTP protocol; this basically means that you have to connect to the LocClim host, port 80, and send a request having the form:

GET /sd/locclim/srv/en/locclim.getValueXML?... HTTP/1.0
and then get a response hawing the form
                   HTTP 200 OK
                   ...
                   
                   XML response
                

For more details about the HTTP protocol please refer to RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1.
In the future we will probably switch to different protocols, possibly based on HTTP, like SOAP, but we will maintain the protocol described in this document for backward compatibility.

Request

The request is an HTTP request having the following URL:

               http://www.fao.org/sd/locclim/srv/en/locclim.getValueXML?ARGLIST
            
Where ARGLIST is a list of HTTP GET request arguments:

Name Default Values Description
method mandatory inverseDistance inverse distance interpolation method
variable mandatory me average temperature (deg C)
min monthly average of daily minimum temperatures (deg C)
max monthly average of daily maximum temperatures (deg C)
pr precipitation (mm - liter/sqm)
pet PET (mm - liter/sqm)
sufr sunshine fraction (% of possible)
windsp wind speed (m/s)
vap water vapor pressure (Hpa)
lon mandatory -180...180 longitude of the query point (dec. degrees)
lat mandatory -90...90 latitude of the query point (dec. degrees)
alt mandatory if altitude correction is requested 0...10000 altitude of the query point (m)
maxDist 300 Km 10...20000 maximum distance of the neighbor stations (Km)
minStations 3 3... minimum number of neighbor stations
maxStations 12 3... maximum number of neighbor stations
exponent 2 0..4 exponent for inverse distance weighting
altCorrection mandatory true,false apply altitude correction
altCorrMaxDist 500 10...20000 maximum distance of neighbor stations for altitude correction (Km)
altCorrMinStations 3 3... minimum number of neighbor stations for altitude correction
altCorrMaxStations 20 3... maximum number of neighbor stations for altitude correction

Response

The HTTP response body contains the XML element <result> containing <value>, <info>, <warning> and <error> children.

               <result>
                  <value period="PERIOD">VALUE</value>
                  ...
                  <info code="CODE" description="DESCRIPTION" period="PERIOD"/>
                  ...
                  <warning code="CODE" description="DESCRIPTION" period="PERIOD"/>
                  ...
               </result>
            

For each <value> element, VALUE is the interpolated value and PERIOD is the month for which the value is valid.

<info>, <warning> and <error> elements contain optional information, warnings and error notifications given by the interpolation method.

CODE contains a standard code for the given information, warning or error, DESCRIPTION is a textual description and the optional period attribute is the month to which the info/warning/error applies. These are the valid code/description pairs for <info> elements.

Code Description
variable climate variable requested
numStations Number of neighbor stations used for the interpolation
altCorrection true iff altitude correction was requested
altCorrNumStations Number of neighbor stations used for altitude correction
altGradient Altitude gradient (units/Km)
avgGradient Average gradient (units/Km)

These are the valid code/description pairs for <warning> elements.

Code Description
minAltGradient min. alt. gradient exceeded (units/Km)
maxAltGradient max. alt. gradient exceeded (units/Km)

If there is an error while processing the request, the HTTP response body contains the XML element <error>.

               <error status="STATUS">
                  ...
               </error>
            

The optional status attribute contains an encoding of the error; the valid values for STATUS are the following:

Value Description
minStations found less than the requested number of neighbor stations
altCorrMinStations found less than the requested number of neighbor stations for altitude correction

Examples
The following is a request for average temperature variable at longitude 0 degrees and latitude 40 degrees, with no altitude correction and all default values.

               http://www.fao.org/sd/locclim/srv/en/locclim.getValueXML?method=inverseDistance
                    &variable=me&lon=0&lat=40&alt=&maxDist=&minStations=&maxStations=&exponent=
                    &altCorrection=false&altCorrMaxDist=&altCorrMinStations=&altCorrMaxStations=
            

The response is:

               <result>
                  <info code="numStations" description="12" />
                  <info code="altCorrection" description="false" />
                  <value period="1">10.513362</value>
                  <value period="2">11.128847</value>
                  <value period="3">12.940931</value>
                  <value period="4">14.85277</value>
                  <value period="5">18.246775</value>
                  <value period="6">20.990204</value>
                  <value period="7">24.18099</value>
                  <value period="8">24.772953</value>
                  <value period="9">22.359606</value>
                  <value period="10">18.340921</value>
                  <value period="11">14.221697</value>
                  <value period="12">11.3174095</value>
                  <info code="variable" description="me" />
               </result>
            

The following is a request for average temperature variable at longitude 0 degrees and latitude 40 degrees, this time with altitude correction and all default values.

               http://www.fao.org/sd/locclim/srv/en/locclim.getValueXML?method=inverseDistance
                    &variable=me&lon=0&lat=40&alt=1000&maxDist=&minStations=&maxStations=&exponent=
                    &altCorrection=true&altCorrMaxDist=&altCorrMinStations=&altCorrMaxStations=
            

The response is:

               <result>
                  <info code="numStations" description="12" />
                  <info code="altCorrection" description="true" />
                  <info code="altCorrNumStations" description="20" />
                  <info code="altGradient" description="-9.103907597569565" period="1" />
                  <info code="altGradient" description="-8.219694263168451" period="2" />
                  <info code="altGradient" description="-6.975472146818723" period="3" />
                  <info code="altGradient" description="-6.371315987824718" period="4" />
                  <info code="altGradient" description="-5.749533376544448" period="5" />
                  <info code="altGradient" description="-4.934261189806267" period="6" />
                  <info code="altGradient" description="-4.689962089192269" period="7" />
                  <info code="altGradient" description="-5.563872235644409" period="8" />
                  <info code="altGradient" description="-6.71829422595291" period="9" />
                  <info code="altGradient" description="-8.225502583523305" period="10" />
                  <info code="altGradient" description="-8.710110163784416" period="11" />
                  <info code="altGradient" description="-8.998702977546886" period="12" />
                  <info code="avgGradient" description="-7.021719069781364" />
                  <value period="1">1.8063419</value>
                  <value period="2">3.2674932</value>
                  <value period="3">6.269557</value>
                  <value period="4">8.7592125</value>
                  <value period="5">12.747893</value>
                  <value period="6">16.27105</value>
                  <value period="7">19.695492</value>
                  <value period="8">19.451641</value>
                  <value period="9">15.9341955</value>
                  <value period="10">10.4740095</value>
                  <value period="11">5.8913045</value>
                  <value period="12">2.7110064</value>
                  <info code="variable" description="me" />
               </result>
            

Java code
The following code implements a program that reads from the command line the LocClim host name and port, a variable code, longitude and latitude, perform an HTTP transaction and prints the data returned by LocClim.

            package org.fao.locclim.utils;
            
            import java.io.*;
            import java.net.*;
            
            public class HTTPSample
            {
               private static final int BUFSIZE = 1024;
            
               public static void main(String args[])
               {
                  if (args.length != 5)
                  {
                     System.err.println("usage: httpsample host port variable longitude latitude");
                     System.exit(1);
                  }
                  String host     = args[0];
                  String port     = args[1];
                  String variable = args[2];
                  String lon      = args[3];
                  String lat      = args[4];
            
                  try
                  {
                     String values = getValues(host, port,
                                              "inverseDistance", variable,
                                               lon, lat,
                                               null, null, null,
                                               null,
                                               false, null,
                                               null, null, null);
                     System.out.println("VALUES:\n" + values);
                  }
                  catch (Exception e)
                  {
                     e.printStackTrace();
                  }
               }
            
               private static String getValues(String host, String port,
                                               String method, String variable,
                                               String lon, String lat,
                                               String maxDist, String minStations, String maxStations,
                                               String exponent,
                                               boolean altCorrection, String alt,
                                               String altCorrMaxDist, String altCorrMinStations, String altCorrMaxStations)
                  throws Exception
               {
                  if (maxDist            == null) maxDist            = "";
                  if (minStations        == null) minStations        = "";
                  if (maxStations        == null) maxStations        = "";
                  if (exponent           == null) exponent           = "";
                  if (alt                == null) alt                = "";
                  if (altCorrMaxDist     == null) altCorrMaxDist     = "";
                  if (altCorrMinStations == null) altCorrMinStations = "";
                  if (altCorrMaxStations == null) altCorrMaxStations = "";
            
                  StringBuffer file = new StringBuffer("/sd/locclim/srv/en/locclim.getValueXML");
                  file.append("?method="             + method);
                  file.append("&variable="           + variable);
                  file.append("&lon="                + lon);
                  file.append("&lat="                + lat);
                  file.append("&maxDist="            + maxDist);
                  file.append("&minStations="        + minStations);
                  file.append("&maxStations="        + maxStations);
                  file.append("&exponent="           + exponent);
                  file.append("&altCorrection="      + altCorrection);
                  file.append("&alt="                + alt);
                  file.append("&altCorrMaxDist="     + altCorrMaxDist);
                  file.append("&altCorrMinStations=" + altCorrMinStations);
                  file.append("&altCorrMaxStations=" + altCorrMaxStations);
            
                  URL url = new URL("http", host, Integer.parseInt(port), file.toString());
                  HttpURLConnection conn = (HttpURLConnection)url.openConnection();
                  InputStream input = conn.getInputStream();
                  ByteArrayOutputStream output = new ByteArrayOutputStream();
                  byte buffer[] = new byte[BUFSIZE];
                  for (int nRead; (nRead = input.read(buffer, 0, BUFSIZE)) > 0; )
                     output.write(buffer, 0, nRead);
                  conn.disconnect();
                  output.close();
                  return output.toString();
               }
            }
            

This is a sample run of the program requesting average temperature at location (0, 40):

               % java -cp . org.fao.locclim.utils.HTTPSample www.fao.org 80 me 0 40
               VALUES:
               <result>
                  <info code="numStations" description="12" />
                  <info code="altCorrection" description="false" />
                  <value period="1">10.513362</value>
                  <value period="2">11.128847</value>
                  <value period="3">12.940931</value>
                  <value period="4">14.85277</value>
                  <value period="5">18.246775</value>
                  <value period="6">20.990204</value>
                  <value period="7">24.18099</value>
                  <value period="8">24.772953</value>
                  <value period="9">22.359606</value>
                  <value period="10">18.340921</value>
                  <value period="11">14.221697</value>
                  <value period="12">11.3174095</value>
                  <info code="variable" description="me" />
               </result>
               % 
            

  Home |  About |  References |  Links |  Contacts |  NRC |  NR |   
  Comments? Please contact us