Technical documentation of Geoportal API

  • FR
  • UK

Index / Documentation / Technical documentation

Elevation service

The Geoportal's elevation service relies upon a REST API and the OGC standard "Web Processing Service" (WPS). This service can be used:

  • with the REST API
  • with WPS standard

As the access to search engines is under web services access rights protection, the URL request must contain an up-to-date token in order to get a result from the elevation service.

Determine the altitude of one or more points

with the REST API :

http://wxs.ign.fr/YOUR_KEY/alti/rest/elevation.{format}

The available formats are json and xml

GET request example 1: zonly = true

The argument "lon" is the list of longitudes of the points of which we want to determine the elevation, the argument "lat" is the list of latitudes of the points of which we want to determine the elevation and the argument "zonly" is a boolean that indicates whether you want only a table of elevations or an extended response. The values returned are the elevations determined for each point in the query.

GET /rest/elevation.json?lon=0.2367|2.1570&lat=48.0551|46.6077&zonly=true
Simple response :

The argument "elevations" is an array of elevations determined for the items requested. The values are given in the order in which the points were provided.

{"elevations": [123.23,19.45]}
GET request example 2: zonly = false & indent = true

The argument "indent" is a Boolean that indicates whether the response will be indented.

GET /rest/elevation.json?lon=0.2367|2.1570&lat=48.0551|46.6077&indent=true
Extended and indented response :

The argument "elevations" is an array of elevations determined at requested points:

  • lat : point latitude
  • lon : point longitude
  • z : viewed point altitude (in meters)
  • acc : accuracy of the viewed point altitude
    {
        "elevations" : [
            {
                "lon": 0.2367,
                "lat": 48.0551,
                "z": 93.58,
                "acc": 2.5
            },
            {
                "lon": 2.157,
                "lat": 46.6077,
                "z": 207.53,
                "acc": 2.5
            }
        ]
    }
GET request example 3: zonly = false & indent = false & delimiter = ","

The argument "delimiter" is used to specify the character used to separate the longitudes and latitudes.

GET /rest/elevation.json?lon=0.2367,2.1570&lat=48.0551,46.6077&delimiter=,
Extended and non indented response with the "," delimiter :

The argument "elevations" is an array of elevations determined at requested points:

  • lat : point latitude
  • lon : point longitude
  • z : viewed point altitude (in meters)
  • acc : accuracy of the viewed point altitude
    {"elevations":[{"lon":0.2367,"lat":48.0551,"z":93.58,"acc":2.5},{"lon":2.157,"lat":46.6077,"z": 207.53,"acc":2.5}]}
Parameters table
parameterDescriptionType / formatMandatoryPossible valuesDefault valueConstraints
zonlyfalse, extended response  
true, simple array of values
booleannofalse  
true
false
indentfalse, non indented response  
true, indented response
booleannofalse  
true
false
delimitercharacter used to separate the longitudes and latitudesstringno'|', ';' ou ',''|'
lonlist of longitudeslist of floatsyes-180 to +180autant de lon que de lat  
le nombre est limité à 50
latlist of latitudeslist of floatsyes-90 to +90autant de lat que de lon  
le nombre est limité à 50
JSONP encapsulation :

JSONP encapsulation is available with XML format of the service. The following request :

http://wxs.ign.fr/CLEF/alti/rest/elevation.xml?lon=2.478036&lat=48.87324&output=json&callback=traiteResultat

gives the foillowing result :

traiteResultat({"http":{"status":200,"error":null},"xml":"<elevations><elevation><lon>2.478</lon><lat>48.8732</lat><z>79.88</z><acc>2.5</acc></elevation></elevations>"})

with WPS standard:

http://wxs.ign.fr/YOUR_KEY/alti/wps?service=WPS&version=1.0.0
POST request example 1: zonly = true
Header
Content-type:text/xml
Request
<?xml version="1.0" encoding="UTF-8"?>
<wps:Execute version="1.0.0" service="WPS"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://www.opengis.net/wps/1.0.0" xmlns:wfs="http://www.opengis.net/wfs"
xmlns:wps="http://www.opengis.net/wps/1.0.0"
xmlns:ows="http://www.opengis.net/ows/1.1" xmlns:gml="http://www.opengis.net/gml"
xmlns:ogc="http://www.opengis.net/ogc"
xmlns:wcs="http://www.opengis.net/wcs/1.1.1" xmlns:xlink="http://www.w3.org/1999/xlink"
xsi:schemaLocation="http://www.opengis.net/wps/1.0.0
http://schemas.opengis.net/wps/1.0.0/wpsAll.xsd">
  <ows:Identifier>gs:WPSElevation</ows:Identifier>
  <wps:DataInputs>
    <wps:Input>
      <ows:Identifier>lon</ows:Identifier>
      <wps:Data>
        <wps:LiteralData>0.2367|2.1570</wps:LiteralData>
      </wps:Data>
    </wps:Input>
    <wps:Input>
        <ows:Identifier>lat</ows:Identifier>
      <wps:Data>
        <wps:LiteralData>48.0551|46.6077</wps:LiteralData>
      </wps:Data>
    </wps:Input>
    <wps:Input>
      <ows:Identifier>crs</ows:Identifier>
      <wps:Data>
        <wps:LiteralData>crs:84</wps:LiteralData>
      </wps:Data>
    </wps:Input>
    <wps:Input>
      <ows:Identifier>format</ows:Identifier>
      <wps:Data>
        <wps:LiteralData>xml</wps:LiteralData>
      </wps:Data>
    </wps:Input>
    <wps:Input>
      <ows:Identifier>indent</ows:Identifier>
      <wps:Data>
        <wps:LiteralData>true</wps:LiteralData>
      </wps:Data>
    </wps:Input>
    <wps:Input>
  </wps:DataInputs>
  <wps:ResponseForm>
    <wps:RawDataOutput>
      <ows:Identifier>result</ows:Identifier>
    </wps:RawDataOutput>
  </wps:ResponseForm>
</wps:Execute>
Extended and indented XML response

The tag elevations is composed of determined altitudes for the requested points.

  • The tag lat is the point latitude
  • The tag lon is the point longitude
  • The tag z is the viewed point altitude (in meters)
  • The tag acc accuracy of the viewed point altitude

The values are given in the order in which the points were provided.

<elevations>
    <elevation>
        <lon>0.2367</lon>
        <lat>48.0551</lat>
        <z>93.58</z>
        <acc>2.5.0</acc>
    </elevation>
    <elevation>
        <lon>2.157</lon>
        <lat>46.6077</lat>
        <z>207.53</z>
        <acc>2.5.0</acc>
    </elevation>
</elevations>
Parameters table
ParameterDescriptionType / formatMandatoryPossible valuesDefault valueConstraints
zonlyfalse, extended response  
true, simple array of values
booleannofalse  
true
false
indentfalse, non indented response  
true, indented response
booleannofalse  
true
false
delimitercharacter used to separate the longitudes and latitudesstringno'|', ';' ou ',''|'
lonlist of longitudeslist of floatsyes-180 to +180as lon as lat < 50
latlist of latitudeslist of floatsyes-90 to +90as lon as lat < 50
formatoutput format of the servicestringnojson  
xml
json
HTTP GET access

The WPS elevation service can be accessed with WPS GET API and thus benefit from JSONP encapsulation. The request :

http://wxs.ign.fr/CLEF/alti/wps?service=WPS&version=1.0.0&request=Execute&identifier=gs%3AWPSElevation&datainputs=lon=2.478036;lat=48.87324;format=xml&rawdataoutput=result&output=json&callback=traiteResultat

Gives the following result :

traiteResultat({"http":{"status":200,"error":null},"xml":"<elevations><elevation><lon>2.478</lon><lat>48.8732</lat><z>79.88</z><acc>2.5</acc></elevation></elevations>"})

Determine the altimetric profile of a curve

with the REST API:

http://wxs.ign.fr/YOUR_KEY/alti/rest/elevationLine.{format}

The available formats are json and xml

GET request example 1: zonly = true

The argument "lon" is the list of longitudes of the points we want to determine the elevation, the argument "lat" is the list of latitudes of the points we want to determine the elevation and the argument "zonly" is a boolean that indicates whether you want only a table elevations or an extended response. The argument "sampling" is the number of points in the sampling. The values returned are the elevations determined for each point in the query.

GET /rest/elevationLine.json?sampling=10&lon=0.2367|2.1570|4.3907&lat=48.0551|46.6077|43.91&indent=true
Indented response:
{
    "elevations": [
        {
            "lon": 0.2367,
            "lat": 48.0551,
            "z": 93.58,
            "acc": 2.5
        },
        {
            "lon": 0.726682,
            "lat": 47.696327,
            "z": 138.01,
            "acc": 2.5
        },
        {
            "lon": 1.209968,
            "lat": 47.335467,
            "z": 62.79,
            "acc": 2.5
        },
        {
            "lon": 1.686696,
            "lat": 46.972574,
            "z": 176.45,
            "acc": 2.5
        },
        {
            "lon": 2.157,
            "lat": 46.6077,
            "z": 207.53,
            "acc": 2.5
        },
        {
            "lon": 2.735486,
            "lat": 45.939827,
            "z": 634.69,
            "acc": 2.5
        },
        {
            "lon": 3.300216,
            "lat": 45.269017,
            "z": 609.78,
            "acc": 2.5
        },
        {
            "lon": 3.85177,
            "lat": 44.5954,
            "z": 1336.03,
            "acc": 2.5
        },
        {
            "lon": 4.122779,
            "lat": 44.257578,
            "z": 266.01,
            "acc": 2.5
        },
        {
            "lon": 4.3907,
            "lat": 43.9191,
            "z": 171.29,
            "acc": 2.5
        }
    ]
}
Parameters table
ParameterDescriptionType / formatMandatoryPossible valuesDefault valueConstraints
samplingnumber of points in the samplingintegerno2 to 50003< 5000
indentfalse, non indented response  
true, indented response
booleannofalse  
true
false
delimitercharacter used to separate the longitudes and latitudesstringno'|', ';' ou ',''|'
lonlist of longitudeslist of floatsyes-180 to +180as lon as lat < 50
latlist of latitudeslist of floatsyes-90 to +90as lon as lat < 50
crsoutput projectionstringnoCRS:84

with WPS standard:

http://wxs.ign.fr/YOUR_KEY/alti/wps?service=WPS&version=1.0.0
Header
Content-type:text/xml
Request
<?xml version="1.0" encoding="UTF-8"?>
<wps:Execute version="1.0.0" service="WPS"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://www.opengis.net/wps/1.0.0" xmlns:wfs="http://www.opengis.net/wfs"
xmlns:wps="http://www.opengis.net/wps/1.0.0"
xmlns:ows="http://www.opengis.net/ows/1.1" xmlns:gml="http://www.opengis.net/gml"
xmlns:ogc="http://www.opengis.net/ogc"
xmlns:wcs="http://www.opengis.net/wcs/1.1.1" xmlns:xlink="http://www.w3.org/1999/xlink"
xsi:schemaLocation="http://www.opengis.net/wps/1.0.0
http://schemas.opengis.net/wps/1.0.0/wpsAll.xsd">
  <ows:Identifier>gs:WPSLineElevation</ows:Identifier>
  <wps:DataInputs>
    <wps:Input>
      <ows:Identifier>lon</ows:Identifier>
      <wps:Data>
        <wps:LiteralData>0.2367|2.1570|4.3907</wps:LiteralData>
      </wps:Data>
    </wps:Input>
    <wps:Input>
      <ows:Identifier>lat</ows:Identifier>
      <wps:Data>
        <wps:LiteralData>48.0551|46.6077|43.9191</wps:LiteralData>
      </wps:Data>
    </wps:Input>
    <wps:Input>
      <ows:Identifier>crs</ows:Identifier>
      <wps:Data>
        <wps:LiteralData>crs:84</wps:LiteralData>
      </wps:Data>
    </wps:Input>
    <wps:Input>
      <ows:Identifier>sampling</ows:Identifier>
      <wps:Data>
        <wps:LiteralData>10</wps:LiteralData>
      </wps:Data>
    </wps:Input>
    <wps:Input>
      <ows:Identifier>format</ows:Identifier>
      <wps:Data>
        <wps:LiteralData>json</wps:LiteralData>
      </wps:Data>
    </wps:Input>
  </wps:DataInputs>
  <wps:ResponseForm>
    <wps:RawDataOutput>
      <ows:Identifier>result</ows:Identifier>
    </wps:RawDataOutput>
  </wps:ResponseForm>
</wps:Execute>
Non indented, in json format response:
{"elevations":[{"lon":0.2367,"lat":48.0551,"z":93.58,"acc":2.5},
{"lon":0.726682,"lat":47.696327,"z":138.01,"acc":2.5},
{"lon":1.209968,"lat":47.335467,"z":62.79,"acc":2.5},
{"lon":1.686696,"lat":46.972574,"z":176.45,"acc":2.5},
{"lon":2.157,"lat":46.6077,"z":207.53,"acc":2.5},
{"lon":2.735486,"lat":45.939827,"z":634.69,"acc":2.5},
{"lon":3.300216,"lat":45.269017,"z":609.78,"acc":2.5},
{"lon":3.85177,"lat":44.5954,"z":1336.03,"acc":2.5},
{"lon":4.122779,"lat":44.257578,"z":266.01,"acc":2.5},
{"lon":4.3907,"lat":43.9191,"z":171.29,"acc":2.5}]}
Parameters table
ParameterDescriptionType / formatMandatoryPossible valuesDefault valueConstraints
samplingnumber of points in the samplingintegerno2 to 50003< 5000
indentfalse, non indented response  
true, indented response
booleannofalse  
true
false
delimitercharacter used to separate the longitudes and latitudesstringno'|', ';' ou ',''|'
lonlist of longitudeslist of floatsyes-180 to +180as lon as lat < 50
latlist of latitudeslist of floatsyes-90 to +90as lon as lat < 50
crsoutput projectionstringnoCRS:84
formatoutput format of the servicestringnojson  
xml
json

Error Handling

If the service returns an error (HTTP code different from 200), the response is in XML or json format. For example:

XML

<error>
    <code>BAD_PARAMETER</code>
    <description>The argument [lon] is mandatory</description>
</error>

JSON

{"error": {
    "code":"BAD_PARAMETER"
    "description":"The argument [lon] is mandatory"
}}