Map feeds

Trap.NZ provides a range of map feeds in OGC (Open Geospatial Consortium) formats which can be linked directly into GIS tools such as ArcGIS, Google Earth and Google Maps, QuantumGIS etc.

To access the feeds you first need to generate an API key.

Generating an API key

In the My account section of Trap.NZ, you can generate an API key that’s associated with your user account. It can only be used for map feeds (which are read-only), and it can be changed any time by generating a new key, which will disable any previously used keys.

image-1639596511730.png

Accessing map feeds

Map feed addresses are in the format:

https://io.trap.nz/geo/trapnz-projects/wfs/apikey/project_id
and
https://io.trap.nz/geo/trapnz-projects/wms/apikey/project_id

for WFS and WMS feeds respectively.

The Project ID is the last part of the URL when you select your project in Trap.NZ.
i.e. when you select the project after logging in, the URL will look something like https://trap.nz/node/123456, and in this case, the Project ID will be 123456.

Note: Some of the map feeds apply to all the projects you are a member of. If you are using those feeds, you still need to select a default project. It doesn’t matter which one.

So for a test user and project the WFS feed looks like this:
https://io.trap.nz/geo/trapnz-projects/wfs/35GElj7FEyGB-gpalO5ptgcEjxmNe7QzOiJNbEPZmSU/123456

(you must generate your own key under the My Account section of the Trap.NZ website)

You can paste these URLs into your GIS system and it will show you the available layers. 

The layers currently available are:
Notes

Trap records map feed attributes

Fields returned

Field

Description

record_id

the trap record UID

project_id

project number

project

project name

line

line name that the trap is associated with

trap_code

the trap code or name

trap_type

the trap type (e.g. DOC 200, A24, etc.)

trap_status

status of the trap when checked

trap_condition

condition of the trap

rebaited

whether the trap was rebaited or not

bait_at_arrival

bait from the previous record (comma delimited if multiple)

bait_details_at_arrival

any bait details from the previous record

bait_at_departure

bait set with the trap record (comma delimited if multiple)

bait_details_at_departure

any bait details set with the trap record

strikes

strike count - for self-resetting traps this would be the number of times it has gone off since the last check. For conventional traps, this would be 1 if sprung.

species_caught

species name

gender

species sex if recorded

maturity

species maturity if recorded (juvenile/mature)

record_date

date of record

recorded_by

name of person who made the record

record_notes

record notes

prev_record_date

date of the previous record

next_record_date

date of the next record

corrected_nights_from_prev_record

RTC calculation (number of trap nights) from the previous record date

corrected_nights_to_next_record

RTC calculation (number of trap nights) to the next record date



Downloading shape files, CSV, linking into Google Earth etc

The map server allows access to WGS 84 and NZTM projections and can also output in many different formats with:

https://io.trap.nz/geo/trapnz-projects/wfs/apikey/project_id?service=WFS&version=1.0.0&request=GetFeature&typeName=layer&outputFormat=format

Output formats:

GML2

outputFormat=GML2

GML3

outputFormat=GML3

Shapefile

outputFormat=shape-zip

JSON

outputFormat=application/json

JSONP

outputFormat=text/javascript

CSV

outputFormat=csv

e.g. to get a shapefile of trap locations:

https://io.trap.nz/geo/trapnz-projects/wfs/apikey/project_id?service=WFS&version=1.0.0&request=GetFeature&typeName=trapnz-projects:my-projects-traps&outputFormat=shape-zip

 

https://io.trap.nz/geo/trapnz-projects/wfs/apikey/project_id?service=WFS&version=2.0.0&request=GetFeature&typeName=trapnz-projects:my-projects-traps&outputFormat=application/vnd.google-earth.kml+xml

 

CSV:

https://io.trap.nz/geo/trapnz-projects/wfs/apikey/project_id?service=WFS&version=2.0.0&request=GetFeature&typeName=trapnz-projects:my-projects-traps&outputFormat=csv

 

You can also view features directly in OpenLayers:

https://io.trap.nz/geo/trapnz-projects/wfs/apikey/project_id?service=WMS&version=1.1.0&request=GetMap&layers=trapnz-projects:my-projects&bbox=174.94,-41.5,174.95,-41&width=708&height=768&srs=EPSG:4326&format=application/openlayers

 

Notes:

The WFS server is set to return a maximum of 10k features per request. If you have more that, you will need to use software (e.g. ArcGIS Pro, or QuantumGIS) to page requests, or include count and startindex parameters . See the WFS specification. 

The shapefile format has a number of limitations - see the Geoserver documentation.  Datetime fields are not supported - only the date will be included.

Accessing the Trap.NZ map feeds with QGIS

Accessing layers

You can add a WFS Layers Layer > Add Layer > Add WFS Layerimage-1639610470879.png

 

Create a new Server Connection and enter the WFS URL in the format described here
https://io.trap.nz/geo/trapnz-projects/wfs/apikey/project_id

The WFS server is set to return a maximum of 10k features per request. If you have more than this number of features you must enable paging and set a page size less than 10,000.  We recommend 5000.

image-1639615373973.png

Save and then click Connect to see the available layers:
image-1639615716385.png

You can then add individual or groups of layers to the map.

Filtering records

You can add a CQL filter to a WFS connection to filter features from the WSF server. This can greatly reduce the amount of data retrieved (speeding up the transfer and improving performance).

For example - if you are only interested in this year’s records, you could add a CQL filter to build the query as a filter before loading the layer from the server.

1. Connect to the server as above to see the list of available layers.

2. Select the layer you want to query (e.g. default-project-trap-records) and click the Build query button

3. In the dialog that appears, enter the following SELECT * FROM "default-project-trap-records" WHERE record_date > '2021-01-01'  (or whatever date you wish to use)
image-1639617358583.png

4. Press OK. The expression used will appear as the Sql value of the target layer:
image-1639617522593.png

When you add the layer now, only the filtered records (features) will be loaded.

 

 

 

 

Accessing the Trap.NZ map feeds with ArcGIS

Accessing layers

  1. You can add a new WFS Server via Connections > Server > New WFS Server:image-1639599998857.png
  2. Enter the WFS URL in the format as described here
    https://io.trap.nz/geo/trapnz-projects/wfs/apikey/project_id
  3. The WFS server is set to return a maximum of 10k features per request. Therefore you must set a page size value smaller than that. We suggest 5k to begin with. Add a custom request parameter of PAGESIZE, with a value of 5000
  4. Leave the Authentication options blank (we are using the API key to control access)

image-1639600516238.png

You will now see the available layers:
image-1639600614050.png

Working with the layers

Right-click or drag the layer to the map to see the features.

Note that, by default, ArcGIS only shows a maximum of 3000 features in the WFS layer. To change this, right-click the layers, select properties and then set the maximum features to something well above what you expect should be returned.

image-1639600835341.png

Filtering records

You can add a CQL filter to a WFS connection to filter features from the WSF server. This can be achieved by adding this parameter to the Custom request parameters - which can greatly reduce the amount of data retrieved (speeding up the transfer and improving performance).  

For example - if you are only interested in this year’s records, you could add a CQL filter as a Custom request parameter 

image-1639601097182.png

Add cql_filter as Parameter, and record_date %3E '2021-01-01' as Value.

Note: symbols such as ‘<’ and ‘>’ need to be URL encoded, hence the %3E in place of >

 

 

Attributions

The trap.nz map feeds and APIs are provided on the condition that you provide a data source attribution in any maps or material that uses these feeds, or data from these feeds.  

E.g.:

"Sourced from trap.nz".
or
"Data sourced from trap.nz".

(if including the attribution on a web page, please link to https://trap.nz)