APIs

Scroll to

Introduction

Web services allow software and web applications to directly access data residing in the LRIS Portal, and consume map tiles relating to various Manaaki Whenua - Landcare Research's (MWLR) datasets. These services are data streaming APIs and come in different flavours, each detailed below.

Web Feature Service (OGC WFS) for accessing vector data from the LRIS portal.
Catalogue Web Service (CS-W) for accessing metadata about the data in the LRIS portal.
Web Map (Tile) Service (OGC WM(T)S) for accessing various map images relating to various MWLR datasets.

You can jump between these sections using the Scroll to function above.

To explore our webmap services:

Manaaki Whenua's Web Map Services.

WFS

Web Feature Service

Web Feature Service (WFS) returns features with geometry and attributes that you can use in any type of geospatial analysis. WFS also supports filters that allow you to perform spatial and attribute queries on the data. For more information go to: Wikipedia | OGC.

For a step-by-step guide on how to use the WFS to retrieve data using ArcGIS, Quantum GIS and MapInfo, see the 'Web Services' user guide provided by LINZ. While this was written for users of the LINZ Data Service web services, the principles are exactly the same for LRIS Portal WFS.

Access control: web service keys

Access to web services is linked to individual user accounts via use of web service keys. A web service key is a sequence of letters and numbers embedded in the URI used to access a web service. A web service key looks like this:

62a95841c73c45789986223b5f1f3cd6 (non-functional)

Only registered users of the LRIS Portal can create web service keys, and web services providing data require a web service key.

Web service keys give MWLR the following benefits:

A reasonable assurance users have accepted the LRIS Terms of Use and applicable data licenses prior to accessing data via web services.
Tracking of web service utilisation back to individual user accounts.
Tracking of web service bugs back to individual user accounts.

Web service keys give users the following benefits:

No usernames, email addresses or passwords are sent unencrypted over the Internet.
Multiple web service keys can be created per LRIS user, allowing personal use in desktop GIS software to be separated from other uses such as enterprise GIS data processing or web applications.
Compatibility with a wide range of client software and web applications.
Separation of high-demand users into different service level brackets.

Creating a web service key

You must be a registered LRIS Portal user to create a web service key.

Click on your profile icon in the menu bar.
Choose "API Keys" from the dropdown list.
On the API Key Management page, click the "Create API Key" button.
Add an appropriate label for the web service key. Examples: "My ArcGIS" or "FME Processing Workflow" or "iPhone Application".
You can either select "Data access only" or choose what services the key can be used for, using "Manual scope".
Click the "Add" button.
Copy the resulting Web Service Key and use it in the URI of a web service (explained below).

Web Feature Service (WFS) for vector layers

Use this URI in your GIS software:

https://lris.scinfo.org.nz/services;key=<YOUR-WEB-SERVICE-KEY>/wfs/

Details:

WFS v1.1.0 and v1.0.0 are supported
GetFeature responses are currently limited to 1,000,000 (1 million) features

The URL for the GetCapabilities document is:

https://lris.scinfo.org.nz/services;key=<YOUR-WEB-SERVICE-KEY>/wfs/?service=WFS&request=GetCapabilities

These capabilities URLs can be found in the "Service & APIs" section of supported layers in the LRIS portal.

CSW

Catalogue Services for the Web (CSW)

The LRIS portal metadata can be searched by third party clients using the OGC CSW protocol supporting HTTP binding to invoke the operations.

The portal supports OpenGIS® Catalogue Services Specification 2.0 - ISO19115/ISO19119 Application Profile for CSW 2.0 of OpenGIS® Catalogue Services Specification (Version 2.0.2, Corrigendum 2 Release, Date: 2007-02-23).

The protocol operations are described in the document OpenGIS® Catalogue Services Specification:

http://portal.opengeospatial.org/files/?artifact_id=20555

The OpenGIS® Catalogue Services Specification 2.0.2 -ISO Metadata Application Profile can be found at

http://portal.opengeospatial.org/files/?artifact_id=21460

The LRIS Portal supports the following CSW operations:

GetCapabilities
DescribeRecord
GetRecords
GetRecordById

Below we describe the different operations supported by the LRIS portal with some examples of usage using the HTTP GET method. Refer to the OpenGIS® Catalogue Services Specification for a complete list of parameters of each CSW operation and also their use using the HTTP POST method.

CSW operations

The LRIS Portal catalogue CSW service can be accessed at:

http://lris.scinfo.org.nz/feeds/csw/

The CSW operations can be accessed using POST, GET methods and SOAP encoding. If you have access to a client that supports the CSW specificatione.g. GIgo, just point the client at the URL above.

GetCapabilities

The GetCapabilities operation allows clients supporting the CSW specification to request service metadata from the LRIS Portal. The response to a GetCapabilities request is an XML document containing service metadata about the server.

Example GetCapabilities GET KVP request:

http://lris.scinfo.org.nz/feeds/csw/?service=CSW&request=GetCapabilities&acceptVersions=2.0.2&acceptFormats=application/xml

DescribeRecord

The DescribeRecord operation allows a client to discover elements of the information model supported by the LRIS Portal. The operation allows some or all of the information model to be described.

Example GET KVP request:

http://lris.scinfo.org.nz/feeds/csw/?service=CSW&request=DescribeRecord&version=2.0.2&outputFormat=application/xml

GetRecords

A GetRecords request allows a client to query the LRIS Portal catalogue. A query is specified in OGC Filter or CQL languages (see the specification for more details about these languages).

The OGC Catalogue Service means of resource discovery comprises two operations: search and present. In the HTTP protocol binding these are combined in the GetRecords operation so that the operation performs a search and a piggybacked present.

The search portion of the GetRecords operation is encoded using the Query element. The Query element includes the parameters typeName and Constraint. The typeName parameter is used to specify which entities from the information model of the catalogue can be queried e.g. typeNames="csw:Record". The Constraint parameter is used to specify which query constraints shall be applied to identify the result set.

Example GET KVP requests

The example below queries the catalogue using a search for any occurrence of the string 'water' in any field. The service, version, and request parameters are standard for an OGC service. The parameters that make this a catalogue search are constraint language, which says the query will be written in CQL and the constraint which is the query (expressed in CQL).

http://lris.scinfo.org.nz/feeds/csw/?service=CSW&request=GetRecords&version=2.0.2&namespace=xmlns%28csw=http://www.opengis.net/cat/csw%29&resultType=results&outputSchema=
http://www.opengis.net/cat/csw/2.0.2&outputFormat=application/xml&maxRecords=10&typeNames=csw:
Record&elementSetName=summary&constraintLanguage=CQL_TEXT&&constraint_language_version=1.1.0&constraint=AnyText Like 'water'

In this case core metadata is returned as a request for the Common Element Set. The Common Element Set is a group of public metadata elements expressed using the nomenclature and syntax of Dublin Core Metadata, ISO 15836. The records returned can be brief, summary or full records; in this example summary records were requested. The maximum number of records to be returned to the client is also specified i.e. 10.

In the example below the TypeName is gmd:MD_Metadata and the outputSchema http://www.isotc211.org/2005/gmd which is the outputschema of the application profile for ISO 19115 metadata with support for XML encoding per ISO 19139.

http://lris.scinfo.org.nz/feeds/csw/?service=CSW&request=GetRecords&version=2.0.2&namespace=xmlns%28csw=http://www.opengis.net/cat/csw%29&resultType=results&outputSchema=
http://www.isotc211.org/2005/gmd&outputFormat=application/xml&maxRecords=10&typeNames=gmd:
MD_Metadata&elementSetName=summary&constraintLanguage=CQL_TEXT&&constraint_language_version=1.1.0&constraint=AnyText Like 'water'

In the next example the search is for metadata records which contain the word ‘water in the title.

http://lris.scinfo.org.nz/feeds/csw/?service=CSW&request=GetRecords&version=2.0.2&namespace=xmlns%28csw=http://www.opengis.net/cat/csw%29&resultType=
results&outputSchema=http://www.opengis.net/cat/csw/2.0.2&outputFormat=application/xml&maxRecords=10&typeNames=
csw:Record&elementSetName=summary&constraintLanguage=CQL_TEXT&&constraint_language_version=1.1.0&constraint=Title LIKE 'water'

Finally in this example the search is for metadata records for which the geographical bounding box coincides fully or partly with a certain area in this case the southernmost part of New Zealand. The ows:BoundingBox element is used to express the spatial extent of the metadata record.

GetRecordById

A GetRecordById request retrieves the default representation of the catalogue metadata records using their identifier. This operation presumes that a previous query has been performed to obtain the identifiers that are used with this operation.

Example GET KVP request

http://lris.scinfo.org.nz/feeds/csw?request=GetRecordById&service=CSW&version=2.0.2&resultType=results&typeNames=csw:Record&elementSetName=full&id=d7c97e89-4c18-1f65-ff95-510aaf000021

The outputSchema parameter can be included in the GetRecordById operation to allow clients to request a representation of a catalogue record other than the default representation. Without the declaration of an Element Set or Output Schema, the server will respond with a default encoding of the results as summary records.

OGC WMS

Web Map Services (OGC WMS)

MWLR provides WM(T)S for some of our science data and background topographic maps via Amazon Elastic Compute Cloud (Amazon EC2) which offers high levels of guaranteed availability and provides scaling of our services to cope with spikes in useage.

Maps relating to various MWLR datasets are available, e.g. New Zealand Land Resource Inventory, layers from the Land Cover Database, Fundamental Soil Layer New Zealand Soil Classification. Multiple map projections are available - e.g. Web Mercator (EPSG: 3857 / 900913), NZTM (EPSG:2193), NZMG (EPSG:27200). These are available as Web Map Services and Cached Tile Services. Using one of the supported tile service protocols allows our maps to be accessed faster.

Details on how to access the WM(T)S and how to use it with various desktop GIS and web applications can be found at http://maps.scinfo.org.nz.

Further information about using these services can be found at https://help.koordinates.com/query-api-and-web-services/.

If you have any questions on any of these services, please contact us at:

lris_support@landcareresearch.co.nz

In this section