Geoportal Resources Access API Reference

Module: Services

Gp.Services

Geoportal web services invocation namespace.

Methods

innerautoComplete(options)

Services/Services.js, line 165

Getting suggestions of probable places names or address based on uncomplete texts, using the autocompletion service of the Geoportal Platform

Name Type Description
options Object

Options for function call.

Name Type Default Description
apiKey String

Access key to Geoportal platform, obtained here.

text String

Text input to complete.

filterOptions.type Array.<String> "StreetAddress" optional

Suggestion types to provide : address ("StreetAddress") and/or place name ("PositionOfInterest").

filterOptions.territory Array.<String> optional

Places where to limit the search of suggestions : "METROPOLE" (Corsica and metropolitan France), "DOMTOM" (French overseas departments and territories), or an INSEE code of a department. No limitation by default. For instance : ['METROPOLE', '31']

maximumResponses Number 10 optional

Maximum number of responses.

onSuccess function

Callback function for getting successful service response. Takes a Gp.Services.AutoCompleteResponse object as a parameter except if "rawResponse" is set to true.

onFailure function optional

Callback function for handling unsuccessful service responses (timeOut, missing rights, ...). Takes a Gp.Error object as parameter.

timeOut Number 0 optional

Number of milliseconds above which a timeOut response will be returned with onFailure callback (see above). Default value is 0 which means timeOut will not be handled.

serverUrl String http (s)://wxs.ign.fr/APIKEY/ols/apis/completion optional

Web service URL. If used, options.apiKey parameter is ignored. Only use if you know what you're doing.

ssl Boolean true optional

Use of HTTP or HTTPS protocol to request the services. HTTPS by default (ssl=true).

protocol String XHR optional

Protocol used to handle dialog with web service. Possible values are 'JSONP' (https://en.wikipedia.org/wiki/JSONP) and 'XHR' (https://en.wikipedia.org/wiki/XMLHttpRequest). Only XHR protocol is supported in a NodeJS environment. Only use if you know what you're doing.

proxyURL String optional

Proxy URL to use when requesting underlying web service. Ignored when options.protocol is set to 'JSONP' value. Only use if you know what you're doing.

callbackSuffix String optional

Callback function name suffix to use in case of a JSONP protocol use (see above), to set your own suffix instead of auto-increment. Ignored when options.protocol is set to 'XHR' value. Only use if you know what you're doing.

httpMethod String GET optional

HTTP method to use when requesting underlying web service in case of a XHR protocol use (see above). Possible values are 'GET' and 'POST'. Ignored when options.protocol is set to 'JSONP' value. Only use if you know what you are doing.

contentType String "application/xml" optional

Content-Type to use when requesting underlying web service in case of a XHR protocol use (see above) and if method HTTP is POST. Ignored when options.protocol is set to 'JSONP' value. Only use if you know what you are doing.

rawResponse Boolean false optional

Setting this parameter to true implies you want to handle the service response by yourself : it will be returned as an unparsed String in onSuccess callback parameter. Only use if you know what you are doing.

onBeforeParse function optional

Callback function for handling service response before parsing (as an unparsed String). Takes a String as a parameter (the raw service response). Returns a String that will be parsed as the service response. Only use if you know what you are doing.

innergeocode(options)

Services/Services.js, line 74

Getting positon of a geographic identifier (places names, address, cadastral parcel, other...) using the geocoding web service of the Geoportal Platform.

Name Type Description
options Object

Options for function call.

Name Type Default Description
apiKey String

Access key to Geoportal platform, obtained here.

location String | Object

Geographic identifier to locate. May be provided as a single String or a structured Object for an address search. In this last case, the following properties are availaibles.

Name Type Description
number Number optional

Street number.

street String optional

Street name.

city String optional

City name.

postalCode Number optional

Postal Code

filterOptions Object optional

Additional filters to apply to search. The following properties may be given.

Name Type Description
bbox Gp.BBox optional

Bounding box where to perform the search. Properties expressed in options.srs coordinates system.

type Array.<String> optional

Geographical identifier types to search. Values currently availables are : "PositionOfInterest" for place names, "StreetAddress" for address search, "CadastralParcel" for Cadastral parcels search. Default is "StreetAddress".

[prop] String optional

Additionnal properties to filter search. Properties depends on options.filterOptions.type, and values type should be "String".



Common Properties availables for all search types :

"municipality", "insee", "department".



Properties availables for address search :

"quality", "ID", "ID_TR" and "territory".



Properties availables for place names search :

"importance", "nature" and "territory".



Properties availables for cadastral parcels search :

"sheet", "section", and "absorbedcity".

maximumResponses Number 25 optional

Maximum number of responses. Default underlying service value applies (25) if not provided.

returnFreeForm Boolean false optional

Set this parameter to true if you wish to have an address returned in a single String (unstructured). If unset, default underlying service value (false) applies.

srs String EPSG:4326 optional

Coordinates System used to expres coordinates for parameters and responses. Default underlying service value (EPSG:4326) applies.

onSuccess function

Callback function for getting successful service response. Takes a Gp.Services.GeocodeResponse object as a parameter except if "rawResponse" is set to true.

onFailure function optional

Callback function for handling unsuccessful service responses (timeOut, missing rights, ...). Takes a Gp.Error object as parameter.

timeOut Number 0 optional

Number of milliseconds above which a timeOut response will be returned with onFailure callback (see above). Default value is 0 which means timeOut will not be handled.

serverUrl String http (s)://wxs.ign.fr/APIKEY/geoportail/ols optional

Web service URL. If used, options.apiKey parameter is ignored. Only use if you know what you're doing.

ssl Boolean true optional

Use of HTTP or HTTPS protocol to request the services. HTTPS by default (ssl=true).

protocol String XHR optional

Protocol used to handle dialog with web service. Possible values are 'JSONP' (https://en.wikipedia.org/wiki/JSONP) and 'XHR' (https://en.wikipedia.org/wiki/XMLHttpRequest). Only XHR protocol is supported in a NodeJS environment. Only use if you know what you're doing.

proxyURL String optional

Proxy URL to use when requesting underlying web service. Ignored when options.protocol is set to 'JSONP' value. Only use if you know what you're doing.

callbackSuffix String optional

Callback function name suffix to use in case of a JSONP protocol use (see above), to set your own suffix instead of auto-increment. Ignored when options.protocol is set to 'XHR' value. Only use if you know what you're doing.

httpMethod String GET optional

HTTP method to use when requesting underlying web service in case of a XHR protocol use (see above). Possible values are 'GET' and 'POST'. Ignored when options.protocol is set to 'JSONP' value. Only use if you know what you are doing.

contentType String "application/xml" optional

Content-Type to use when requesting underlying web service in case of a XHR protocol use (see above) and if method HTTP is POST. Ignored when options.protocol is set to 'JSONP' value. Only use if you know what you are doing.

rawResponse Boolean false optional

Setting this parameter to true implies you want to handle the service response by yourself : it will be returned as an unparsed String in onSuccess callback parameter. Only use if you know what you are doing.

onBeforeParse function optional

Callback function for handling service response before parsing (as an unparsed String). Takes a String as a parameter (the raw service response). Returns a String that will be parsed as the service response. Only use if you know what you are doing.

Example
Gp.Services.geocode ({
    apiKey : "jhyvi0fgmnuxvfv0zjzorvdn",
    location : "73 avenue de Paris, Saint-Mandé",
    // traitement des resultats
    onSuccess  : function (result) {
        console.log("found (x:"+result.position.x+", y:"+result.position.y+")") ;
    }
}) ;

innergetAltitude(options)

Services/Services.js, line 42

Getting elevations in or along of one or several points on french territories using the elevation services of the Geoportal Platform.

Two use cases are availables :

  1. getting elevations of the given points : don't use the options.sampling parameter ;
  2. getting a regular set of elevations along the given points : use the options.sampling parameter.
Name Type Description
options Object

Options for function call.

Name Type Default Description
apiKey String

Access key to Geoportal platform, obtained here.

positions Array.<Object>

Array of positions ({lon:float, lat:float}) expressed in CRS:84 coordinates system, where to get elevations. 50 positions maximum may be given. 2 positions minimum are required if you use the options.sampling parameter.

sampling Number optional

Number of points to use (between 2 and 5000) in order to compute an elevation path. The points given with the options.positions parameter are used to fix the planimetric path along which the elevations will be computed.

If not used, only elevations of these positions will be returned.

zonly Boolean false optional

Set this parameter to true if you only want to have elevations returned without corresponding coordinates.

onSuccess function

Callback function for getting successful service response. Takes a Gp.Services.AltiResponse object as a parameter, except if "rawResponse" is set to true.

onFailure function optional

Callback function for handling unsuccessful service responses (timeOut, missing rights, ...). Takes a Gp.Error object as parameter.

timeOut Number 0 optional

Number of milliseconds above which a timeOut response will be returned with onFailure callback (see above). Default value is 0 which means timeOut will not be handled.

serverUrl String http (s)://wxs.ign.fr/APIKEY/alti/rest/elevation.json optional

Web service URL. If used, options.apiKey parameter is ignored. Only use if you know what you're doing.

ssl Boolean true optional

Use of HTTP or HTTPS protocol to request the services. HTTPS by default (ssl=true).

protocol String XHR optional

Protocol used to handle dialog with web service. Possible values are 'JSONP' (https://en.wikipedia.org/wiki/JSONP) and 'XHR' (https://en.wikipedia.org/wiki/XMLHttpRequest). Only XHR protocol is supported in a NodeJS environment. Only use if you know what you're doing.

proxyURL String optional

Proxy URL to use when requesting underlying web service. Ignored when options.protocol is set to 'JSONP' value. Only use if you know what you're doing.

callbackSuffix String optional

Callback function name suffix to use in case of a JSONP protocol use (see above), to set your own suffix instead of auto-increment. Ignored when options.protocol is set to 'XHR' value. Only use if you know what you're doing.

httpMethod String GET optional

HTTP method to use when requesting underlying web service in case of a XHR protocol use (see above). Possible values are 'GET' and 'POST'. Ignored when options.protocol is set to 'JSONP' value. Only use if you know what you are doing.

contentType String "application/xml" optional

Content-Type to use when requesting underlying web service in case of a XHR protocol use (see above) and if method HTTP is POST. Ignored when options.protocol is set to 'JSONP' value. Only use if you know what you are doing.

rawResponse Boolean false optional

Setting this parameter to true implies you want to handle the service response by yourself : it will be returned as an unparsed String in onSuccess callback parameter. Only use if you know what you are doing.

onBeforeParse function optional

Callback function for handling service response before parsing (as an unparsed String). Takes a String as a parameter (the raw service response). Returns a String that will be parsed as the service response. Only use if you know what you are doing.

api String 'REST' optional

What API to use for interacting with underlying web service : 'REST' or 'WPS'. Only use if you know what you are doing.

outputFormat String 'xml' optional

Output format for underlying web service response : 'xml' or 'json'. Only use if you know what you are doing.

innergetConfig(options)

Services/Services.js, line 18

Access to Geoportal resources metadata availables with one ore several keys, using Auto-configuration service of the Geoportal platform.

Name Type Description
options Object

Options for function call.

Name Type Default Description
apiKey String

Access key to Geoportal platform, obtained here.

onSuccess function

Callback function for getting successful service response. Takes a Gp.Services.GetConfigResponse object as a parameter except if "rawResponse" parameter is set to true : a String will be returned.

onFailure function optional

Callback function for handling unsuccessful service responses (timeOut, missing rights, ...). Takes a Gp.Error object as parameter.

timeOut Number 0 optional

Number of milliseconds above which a timeOut response will be returned with onFailure callback (see above). Default value is 0 which means timeOut will not be handled.

serverUrl String http (s)://wxs.ign.fr/APIKEY/autoconf optional

Web service URL. If used, options.apiKey parameter is ignored. Only use if you know what you're doing.

ssl Boolean true optional

Use of HTTP or HTTPS protocol to request the services. HTTPS by default (ssl=true).

protocol String JSONP optional

Protocol used to handle dialog with web service. Possible values are 'JSONP' (https://en.wikipedia.org/wiki/JSONP) and 'XHR' (https://en.wikipedia.org/wiki/XMLHttpRequest). Only XHR protocol is supported in a NodeJS environment. Only use if you know what you're doing.

proxyURL String optional

Proxy URL to use when requesting an underlying web service. Ignored when options.protocol is set to 'JSONP' value. Only use if you know what you're doing.

callbackSuffix String optional

Callback function name suffix to use in case of a JSONP protocol use (see above), to set your own suffix instead of auto-increment. Ignored when options.protocol is set to 'XHR' value. Only use if you know what you're doing.

httpMethod String GET optional

HTTP method to use when requesting underlying web service in case of a XHR protocol use (see above). Possible values are 'GET' and 'POST'. Ignored when options.protocol is set to 'JSONP' value. Only use if you know what you are doing.

contentType String "application/xml" optional

Content-Type to use when requesting underlying web service in case of a XHR protocol use (see above) and if method HTTP is POST. Ignored when options.protocol is set to 'JSONP' value. Only use if you know what you are doing.

rawResponse Boolean false optional

Setting this parameter to true implies you want to handle the service response by yourself : it will be returned as an unparsed String in onSuccess callback parameter. Only use if you know what you are doing.

onBeforeParse function optional

Callback function for handling service response before parsing (as an unparsed String). Takes a String as a parameter (the raw service response). Returns a String that will be parsed as the service response. Only use if you know what you are doing.

innerisoCurve(options)

Services/Services.js, line 225

Computing a set of places (curve) reachable from a given point (or from where to start to reach a given point) within a time or distance constraint using the isochrone service of the Geoportal Platform.

Name Type Description
options Object

Options for function call.

Name Type Default Description
apiKey String

Access key to Geoportal platform, obtained here.

position Gp.Point

Start or Arrival (options.reverse===true) Point for the computing. Expressed in CRS:84 coordinates system (position.x corresponds to longitude, position.y corresponds to latitude).

graph String "Voiture" optional

User profile to use to compute the isoCurve : "Voiture" (using a vehicule) or "Pieton" (pedestrian). Has an influence on the kind of roads to use and the average speed.

exclusions Array.<String> optional

Indicates if route has to avoid some features ("toll", "bridge" or "tunnel").

method String "time" optional

Computing method to use : "time" (using a duration as a constraint) or "distance" (using a distance as a constraint).

time Float

Maximum duration (expressed in seconds) to use when options.method is set to "time".

distance Float

Maximum distance (expressed in meters) to use when options.method is set to "distance".

reverse Boolean false optional

Set this parameter to true if you want options.position to be the destination (instead of departure) for the computing.

smoothing Boolean false optional

Set this parameter to true if you want the resulting geometry to be smoothed.

holes Boolean false optional

Set this parameter to true if you want the resulting geometry (polygon) to have holes if pertinent.

onSuccess function

Callback function for getting successful service response. Takes a Gp.Services.IsoCurveResponse object as a parameter except if "rawResponse" is set to true.

onFailure function optional

Callback function for handling unsuccessful service responses (timeOut, missing rights, ...). Takes a Gp.Error object as parameter.

timeOut Number 0 optional

Number of milliseconds above which a timeOut response will be returned with onFailure callback (see above). Default value is 0 which means timeOut will not be handled.

outputFormat String 'json' optional

Output format ("json" or "xml") to use for underlying webService. Only use if you know what you are doing.

serverUrl String http (s)://wxs.ign.fr/APIKEY/isochrone/isochrone.json optional

Web service URL. If used, options.apiKey parameter is ignored. Only use if you know what you're doing.

ssl Boolean true optional

Use of HTTP or HTTPS protocol to request the services. HTTPS by default (ssl=true).

protocol String XHR optional

Protocol used to handle dialog with web service. Possible values are 'JSONP' (https://en.wikipedia.org/wiki/JSONP) and 'XHR' (https://en.wikipedia.org/wiki/XMLHttpRequest). Only XHR protocol is supported in a NodeJS environment. Only use if you know what you're doing.

proxyURL String optional

Proxy URL to use when requesting underlying web service. Ignored when options.protocol is set to 'JSONP' value. Only use if you know what you're doing.

callbackSuffix String optional

Callback function name suffix to use in case of a JSONP protocol use (see above), to set your own suffix instead of auto-increment. Ignored when options.protocol is set to 'XHR' value. Only use if you know what you're doing.

httpMethod String GET optional

HTTP method to use when requesting underlying web service in case of a XHR protocol use (see above). Possible values are 'GET' and 'POST'. Ignored when options.protocol is set to 'JSONP' value. Only use if you know what you are doing.

contentType String "application/xml" optional

Content-Type to use when requesting underlying web service in case of a XHR protocol use (see above) and if method HTTP is POST. Ignored when options.protocol is set to 'JSONP' value. Only use if you know what you are doing.

rawResponse Boolean false optional

Setting this parameter to true implies you want to handle the service response by yourself : it will be returned as an unparsed String in onSuccess callback parameter. Only use if you know what you are doing.

onBeforeParse function optional

Callback function for handling service response before parsing (as an unparsed String). Takes a String as a parameter (the raw service response). Returns a String that will be parsed as the service response. Only use if you know what you are doing.

innerreverseGeocode(options)

Services/Services.js, line 133

Retrieving geographical identifiers (place names, address, cadastral parcels, ...) near a given position, using the reverse geocoding web service of the Geoportal Platform.

Name Type Description
options Object

Options for function call.

Name Type Default Description
apiKey String

Access key to Geoportal platform, obtained here.

position Gp.Point

Reference position where to search geographical identifiers. Its coordinates are expressed in the coordinates system given with options.srs parameter. (default is CRS:84, that means position.x is the longitude and position.y the latitude)

filterOptions Object optional

Additional filters to apply to search. The following properties may be given.

Name Type Description
type Array.<String> optional

Geographical identifier types to search. Values currently availables are : "PositionOfInterest" for place names, "StreetAddress" for address search, "CadastralParcel" for Cadastral parcels search. Default is "StreetAddress".

bbox Gp.BBox optional

Bounding box where to perform the search. Expressed in options.srs coordinates system.

circle Gp.Circle optional

Circle where to perform the search. Expressed in options.srs coordinates system.

polygon Array.<Gp.Point> optional

Polygon where to perform the search. Expressed in options.srs coordinates system.

maximumResponses Number optional

Maximum number of responses. Default underlying service value applies (25) if not provided.

returnFreeForm Boolean false optional

Set this parameter to true if you wish to have an address returned in a single String (unstructured). If unset, default underlying service value (false) applies.

srs String CRS:84 optional

Coordinates System used to express coordinates for parameters and responses. Only WGS 84 geographical positioning is supported. Therefore, two values are allowed : "CRS:84" (position.x is the longitude and position.y the latitude) and "EPSG:4326" (position.x is the latitude and position.y the longitude) . Default is CRS:84.

onSuccess function

Callback function for getting successful service response. Takes a Gp.Services.GeocodeResponse object as a parameter except if "rawResponse" is set to true.

onFailure function optional

Callback function for handling unsuccessful service responses (timeOut, missing rights, ...). Takes a Gp.Error object as parameter.

timeOut Number 0 optional

Number of milliseconds above which a timeOut response will be returned with onFailure callback (see above). Default value is 0 which means timeOut will not be handled.

serverUrl String http (s)://wxs.ign.fr/APIKEY/geoportail/ols optional

Web service URL. If used, options.apiKey parameter is ignored. Only use if you know what you're doing.

ssl Boolean true optional

Use of HTTP or HTTPS protocol to request the services. HTTPS by default (ssl=true).

protocol String XHR optional

Protocol used to handle dialog with web service. Possible values are 'JSONP' (https://en.wikipedia.org/wiki/JSONP) and 'XHR' (https://en.wikipedia.org/wiki/XMLHttpRequest). Only XHR protocol is supported in a NodeJS environment. Only use if you know what you're doing.

proxyURL String optional

Proxy URL to use when requesting underlying web service. Ignored when options.protocol is set to 'JSONP' value. Only use if you know what you're doing.

callbackSuffix String optional

Callback function name suffix to use in case of a JSONP protocol use (see above), to set your own suffix instead of auto-increment. Ignored when options.protocol is set to 'XHR' value. Only use if you know what you're doing.

httpMethod String GET optional

HTTP method to use when requesting underlying web service in case of a XHR protocol use (see above). Possible values are 'GET' and 'POST'. Ignored when options.protocol is set to 'JSONP' value. Only use if you know what you are doing.

contentType String "application/xml" optional

Content-Type to use when requesting underlying web service in case of a XHR protocol use (see above) and if method HTTP is POST. Ignored when options.protocol is set to 'JSONP' value. Only use if you know what you are doing.

rawResponse Boolean false optional

Setting this parameter to true implies you want to handle the service response by yourself : it will be returned as an unparsed String in onSuccess callback parameter. Only use if you know what you are doing.

onBeforeParse function optional

Callback function for handling service response before parsing (as an unparsed String). Takes a String as a parameter (the raw service response). Returns a String that will be parsed as the service response. Only use if you know what you are doing.

innerroute(options)

Services/Services.js, line 192

Getting a route from one point to another using the route service of the Geoportal Platform.

Name Type Description
options Object

Options for function call.

Name Type Default Description
apiKey String

Access key to Geoportal platform, obtained here.

routePreference String "fastest" optional

Indicates the way to compute the route : "fastest" (time optimisation) or "shortest" (distance optimisation).

startPoint Gp.Point

Start point of the route. Expressed in CRS:84 coordinates system (startPoint.x corresponds to longitude, startPoint.y corresponds to latitude).

endPoint Gp.Point

End point of the route. Expressed in CRS:84 coordinates system (endPoint.x corresponds to longitude, endPoint.y corresponds to latitude).

viaPoints Array.<Gp.Point> optional

Ordered via Points of the route. Expressed in CRS:84 coordinates system (viaPoints[i].x corresponds to longitude, viaPoints[i].y corresponds to latitude).

graph String "Voiture" optional

User profile to use to compute the route : "Voiture" (using a vehicule) or "Pieton" (pedestrian). Has an influence on the kind of roads the route may use and the average speed.

exclusions Array.<String> optional

Indicates if route has to avoid some features ("toll", "bridge" or "tunnel").

geometryInInstructions Boolean false optional

Indicates if route geometry has to be also returned with route instructions.

provideBoundingBox Boolean true optional

Indicates if route instructions has to be localised with a BBOX in the response.

distanceUnit String "km" optional

The unit used to provide distances in the response ("m" or "km").

onSuccess function

Callback function for getting successful service response. Takes a Gp.Services.RouteResponse object as a parameter except if "rawResponse" is set to true.

onFailure function optional

Callback function for handling unsuccessful service responses (timeOut, missing rights, ...). Takes a Gp.Error object as parameter.

timeOut Number 0 optional

Number of milliseconds above which a timeOut response will be returned with onFailure callback (see above). Default value is 0 which means timeOut will not be handled.

outputFormat String 'json' optional

Output format ("json" or "xml") to use for underlying webService. Only use if you know what you are doing.

serverUrl String http (s)://wxs.ign.fr/APIKEY/itineraire/rest/route.json optional

Web service URL. If used, options.apiKey parameter is ignored. Only use if you know what you're doing.

ssl Boolean true optional

Use of HTTP or HTTPS protocol to request the services. HTTPS by default (ssl=true).

protocol String XHR optional

Protocol used to handle dialog with web service. Possible values are 'JSONP' (https://en.wikipedia.org/wiki/JSONP) and 'XHR' (https://en.wikipedia.org/wiki/XMLHttpRequest). Only XHR protocol is supported in a NodeJS environment. Only use if you know what you're doing.

proxyURL String optional

Proxy URL to use when requesting underlying web service. Ignored when options.protocol is set to 'JSONP' value. Only use if you know what you're doing.

callbackSuffix String optional

Callback function name suffix to use in case of a JSONP protocol use (see above), to set your own suffix instead of auto-increment. Ignored when options.protocol is set to 'XHR' value. Only use if you know what you're doing.

httpMethod String GET optional

HTTP method to use when requesting underlying web service in case of a XHR protocol use (see above). Possible values are 'GET' and 'POST'. Ignored when options.protocol is set to 'JSONP' value. Only use if you know what you are doing.

contentType String "application/xml" optional

Content-Type to use when requesting underlying web service in case of a XHR protocol use (see above) and if method HTTP is POST. Ignored when options.protocol is set to 'JSONP' value. Only use if you know what you are doing.

rawResponse Boolean false optional

Setting this parameter to true implies you want to handle the service response by yourself : it will be returned as an unparsed String in onSuccess callback parameter. Only use if you know what you are doing.

onBeforeParse function optional

Callback function for handling service response before parsing (as an unparsed String). Takes a String as a parameter (the raw service response). Returns a String that will be parsed as the service response. Only use if you know what you are doing.