Spatial Web Services
Layers Web Services
These webservices provide spatial search capabilities. These services are in addition to occurrence searching
services available. For a full listing of services go to at api.nbnatlas.org
Please send any bug reports, suggestions for improvements or new services to:
developers 'AT' ala.org.au
- Layers
- Get a list of all layers: /layers
- Get a list of all environmental/gridded layers: /layers/grids
- Get a list of all contextual layers: /layers/shapes
- Fields
- Get a list of all fields: /fields
- Get information about a specific field, given a field id: /ws/field/{id} e.g. /field/cl22
- Objects
- Get a list of objects, given the field id: /ws/objects/{id} e.g. /objects/cl22
- Get information about an object, given its pid /ws/object/{pid} e.g. /object/3742602
- Download a shape object as KML, given its pid: /ws/shape/kml/{pid} e.g. /shape/kml/3742602
- Download a shape object as WKT, given its pid: /ws/shape/wkt/{pid} /shape/wkt/3742602
- Download a shape object as GeoJSON, given its pid: /ws/shape/geojson/{pid} /shape/geojson/3742602
- Download a shape object as a zipped ESRI shape (.shp) file, given its pid: /ws/shape/shp/{pid} /shape/shp/3742602
- Get the nearest objects to a coordinate /ws/objects/{id}/{lat}/{lng}?limit=40 e.g. /objects/cl915/-22.465864536394/124.419921875?limit=10
- Upload geometry as WKT: POST request to /ws/shape/upload/wkt. POST data must be a json object containing the following fields:
- wkt: a WKT string describing the geometry
- name: the name of the geometry (string)
- description: description of the geometry (string)
- user_id: user id associated with api key (see below) (number)
- api_key: spatial portal api key - see http://auth.ala.org.au/apikey/
- Upload geometry as geojson: POST request to /ws/shape/upload/geojson. POST data must be a json object containing the following fields:
- geojson: a geojson string describing the geometry
- name: the name of the geometry (string)
- description: description of the geometry (string)
- user_id: user id associated with api key (see below) (string)
- api_key: spatial portal api key (string) - see http://auth.ala.org.au/apikey/
- Upload geometry as point and radius POST request to /ws/shape/upload/{latitude}/{longitude}/{radius}. POST data must be a json object containing the following fields:
- name: the name of the geometry (string)
- description: description of the geometry (string)
- user_id: user id associated with api key (see below) (string)
- api_key: spatial portal api key (string)- see http://auth.ala.org.au/apikey/
-
Upload geometry from shape file feature.This is a two step process:
- Upload zipped shape file: A shape file must first be uploaded in a zip archive before its features can be used to create objects. A shape file can be uploaded by one of two methods:
- Multipart POST: Multipart POST to /ws/shape/upload/shp?user_id={user_id}&api_key={api_key}, with the zipped shape file in the multipart form data.
- Regular POST: Regular POST to /ws/shape/upload/shp with. The POST data must be a json object containing the following fields:
- shp_file_url: description of the geometry (string)
- user_id: user id associated with api key (see below) (String)
- api_key: spatial portal api key (string) - see http://auth.ala.org.au/apikey/
-
Create object from shape file feature: Once a shape file has been uploaded, its features can be used to create objects. Send a POST request to: /shape/upload/shp/{shapeId}/{featureIndex}, where {shapeId} is the id of the uploaded shape file, and {featureIndex}
is the numeric index of the desired feature, both returned in the response of the shape file upload method (see above). POST data must be a JSON object containing the following fields:
- name: the name of the geometry (string)
- description: description of the geometry (string)
- user_id: user id associated with api key (see below) (string)
- api_key: spatial portal api key (string)- see http://auth.ala.org.au/apikey/
- Upload zipped shape file: A shape file must first be uploaded in a zip archive before its features can be used to create objects. A shape file can be uploaded by one of two methods:
-
Update geometry from shape file feature. POST request to: /shape/upload/shp/{objectPid}/{shapeId}/{featureIndex}, where {objectPid} is the id of the object to update, {shapeId} is the
id of the uploaded shape file and {featureIndex} is the numeric index of the desired feature, as returned in the response of the shape file upload method (see above). POST data must be a JSON object containing the following fields:
- name: the name of the geometry (string)
- description: description of the geometry (string)
- user_id: user id associated with api key (see below) (string)
- api_key: spatial portal api key (string)- see http://auth.ala.org.au/apikey/
- Points Of Interest
- Create point of interest POST request to /ws/poi. POST data must be a json object containing the following fields:
- name: name of the point of interest (string)
- type: the type of point of interest e.g. "photo point"
- description: description of the point of interest (string) - optional
- latitude: latitude (number)
- longitude: longitude (number)
- user_id: user id associated with api key (see below) (number)
- api_key: spatial portal api key - see http://auth.ala.org.au/apikey/
- object_id: id of the object associated with this point of interest (string) - optional
- bearing: compass bearing in degrees (number) - optional
- focal_length: focal length in millimetres (number) - optional
- Update point of interest POST request to /ws/poi/{id}, where {id} is the point of interest id.
POST data must be a json object containing the following fields:
- name: name of the point of interest (string)
- type: the type of point of interest e.g. "photo point"
- description: description of the point of interest (string) - optional
- latitude: latitude (number)
- longitude: longitude (number)
- user_id: user id associated with api key (see below) (number)
- api_key: spatial portal api key - see http://auth.ala.org.au/apikey/
- object_id: id of the object associated with this point of interest (string) - optional
- bearing: compass bearing in degrees (number) - optional
- focal_length: focal length in millimetres (number) - optional
- Get point of interest details GET request to /ws/poi/{id}, where {id} is the point of interest id.
Return value: a JSON object containing the following fields:
- name: id of the point of interest (string)
- name: id of the point of interest (string)
- type: the type of point of interest e.g. "photo point"
- description: description of the point of interest (string)
- latitude: latitude (number)
- longitude: longitude (number)
- user_id: user id of the user who created the point of interest
- object_id: id of the object associated with this point of interest (string)
- bearing: compass bearing in degrees (number)
- focal_length_millimetres: focal length in millimetres (number)
- Delete point of interest DELETE request to /ws/poi/{id}?user_id={user id}&api_key={api key}, where {id} is the point of interest id, and the user id and api key are supplied as url arguments. Return value: a JSON object containing a boolean field "deleted" which indicates whether or not the point of interest was successfully deleted e.g. {"deleted":true}
- Retrieve details of all points of interest within a specified radius of a point: GET request to /intersect/poi/pointradius/{latitude}/{longitude}/{radius} - radius is in kilometres e.g. /intersect/poi/pointradius/-35.30821/149.12444/5
- Retrieve details of all points of interest that intersect with a geometry specified using wkt: GET or POST request to /intersect/poi/wkt with request parameter "wkt" containing the wkt geometry to intersect e.g. /intersect/poi/wkt?wkt=POLYGON((149.09641919556 -35.320882015603,149.15598569337 -35.320882015603,149.15598569337 -35.271424614118,149.09641919556 -35.271424614118,149.09641919556 -35.320882015603))
- Retrieve details of all points of interest that intersect with a geometry specified using geojson: GET or POST request to /intersect/poi/geojson with request parameter "geojson" containing the geojson geometry to intersect e.g. {"type":"Polygon","coordinates":[[[125.5185546875,-21.446934836644001],[128.2431640625,-21.446934836644001],[128.2431640625,-19.138942324356002],[125.5185546875,-19.138942324356002],[125.5185546875,-21.446934836644001]]]}
- Retrieve details of all points of interest that intersect an object: GET request to /intersect/poi/object/{id} - where "id" is the object id e.g. /intersect/poi/object/3742602
- Create point of interest POST request to /ws/poi. POST data must be a json object containing the following fields:
- Search
- Search for gazetteer localities: /search?q={free text} e.g. /search?q=canberra
- Intersect
- Intersect a layer(s) at a given set of coordinates. Multiple field ids or layer names can be specified separated by a comma (e.g. cl22,cl23): /ws/intersect/{id}/{latitude}/{longitude} e.g. /intersect/cl22/-29.911/132.769
- Batch intersect a layer(s) at given coordinates. Multiple field ids or layer names can be specified separated by a comma (e.g. cl22,cl23). Limited to 1000 coordinates.: /ws/intersect/batch e.g. /intersect/batch?fids=cl22&points=-29.911,132.769,-20.911,122.769
- Check batch intersect status with a batchId: /ws/intersect/batch/{batchId} e.g. /ws/intersect/batch/1234
- Download a finished batch intersect with a batchId as zipped file 'sample.csv': /ws/intersect/batch/download/{batchId} e.g. /ws/intersect/batch/download/1234
- Distributions
- Get a list of all distributions: /distributions
- min_depth - min depth in metres
- max_depth - max depth in metres
- wkt - well known text string to use to intersect distributions
- fid - the id for the alayer
- objectName - the name of the object in the layer used to intersect distributions
- coastal - Values are true/false or null (= not entered); false = non-estuarine, true = coastal
- desmersal - Values are true/false or null (= not entered); false = non-estuarine, true = desmersal
- estuarine - Values are true/false or null (= not entered); false = non-estuarine, true = estuarine
- pelagic - Values are true/false or null
- groupName - e.g. "sharks", "rays", "chimaeras"
- family - e.g. "Alopiidae". For multiple families add multiple "&family=?" params to URL
- familyLsid - e.g. "urn:lsid:biodiversity.org.au:afd.taxon:7cb7f40d-143f-49cc-839d-613259786a42"
- genus - e.g. "Alopias" For multiple genera add multiple "&genus=?" params to URL
- genusLsid - e.g. "urn:lsid:biodiversity.org.au:afd.taxon:557d7f85-a430-4424-a7ae-7fca52b8b443"
- dataResourceUid - e.g. "dr803" to only retrieve distributions supplied by a specific resource e.g. ANFC (dr803)
- Get a count of all distributions by family: /distributions/counts
Same supported parameters as /distributions/.
- Get a list of all distributions for radius: /distributions/radius
- lat - latitude
- lon - longitude
- radius - radius in metres
- min_depth - min depth in metres
- max_depth - max depth in metres
- coastal - Values are true/false or null (= not entered); false = non-estuarine, true = coastal
- desmersal - Values are true/false or null (= not entered); false = non-estuarine, true = desmersal
- estuarine - Values are true/false or null (= not entered); false = non-estuarine, true = estuarine
- pelagic - Values are true/false or null
- groupName - e.g. "sharks", "rays", "chimaeras"
- family - e.g. "Alopiidae". For multiple families add multiple e.g. "?family=Alopiidae&family=Rhinochimaeridae" params to URL
- familyLsid - e.g. "urn:lsid:biodiversity.org.au:afd.taxon:7cb7f40d-143f-49cc-839d-613259786a42"
- genus - e.g. "Alopias" For multiple genera add multiple "&genus=?" params to URL
- genusLsid - e.g. "urn:lsid:biodiversity.org.au:afd.taxon:557d7f85-a430-4424-a7ae-7fca52b8b443"
- dataResourceUid - e.g. "dr803" to only retrieve distributions supplied by a specific resource e.g. ANFC (dr803)
- Get a count of all distributions for radius by family: /distributions/radius
Same supported parameters as /distributions/radius.
- Get information about a specific distribution, given a spcode: /ws/distribution/{spcode} e.g. /distribution/37031044 (Arafura Skate)
- Get information about a specific distribution, given a LSID: /ws/distribution/lsid/{lsid} e.g. /distribution/lsid/urn:lsid:biodiversity.org.au:afd.taxon:2386db84-1fdd-4c33-a2ea-66e13bfc8cf8 (Kapala Stingaree)
- Get a list of all distributions: /distributions
- Tabulation
- Get a list of tabulations: /tabulations
- Get tabulation for a single layer as HTML: /ws/tabulation/cl22/html?wkt={valid wkt polygon geometry} e.g. /tabulation/cl22/html.html?wkt=POLYGON((130 -24,138 -24,138 -20,130 -20,130 -24))
- Get area tabulation for 2 layers, given their id's: /ws/tabulation/area/{id}/{id} e.g. /tabulation/area/cl22/cl23
- Get area tabulation as CSV for 2 layers, given their id's: /ws/tabulation/area/{id}/{id}/tabulation.csv e.g. /tabulation/area/cl22/cl23/tabulation.csv
- Get area tabulation as HTML for 2 layers, given their id's: /ws/tabulation/area/{id}/{id}/tabulation.html e.g. /tabulation/area/cl22/cl23/tabulation.html
- Get tabulation within an area as HTML for 2 layers, given their id's: /ws/tabulation/{id}/{id}/html?wkt={valid wkt polygon geometry} e.g. /tabulation/cl22/cl23/html.html?wkt=POLYGON((130 -24,138 -24,138 -20,130 -20,130 -24))
- RIF-CS
- Layer information in RIF-CS format: /layers/rif-cs.xml
Analysis Web Services
There are three stages in using analysis web services; Start analysis, Monitor analysis, Retrieve output.
- MaxEnt Prediction
Start Maxent /alaspatial/ws/maxent, POST request. E.g. http://spatial.ala.org.au/alaspatial/ws/maxent
Parameters:- taxonid - this will be the name of maxent model. E.g. “Macropus Rufus”.
- taxonlsid – Life Science Identifier that is required but not currently used. E.g. “urn:lsid:biodiversity.org.au:afd.taxon:aa745ff0-c776-4d0e-851d-369ba0e6f537”.
- species – A csv file with a header record and containing all species points. Column order is species name, longitude (decimal degrees), latitude (decimal degrees). E.g. “Species,longitude,latitude Macropus Rufus,122,-20 Macropus Rufus,123,-18”.
- area - bounding area in Well Known Text (WKT) format. E.g. “POLYGON((118 -30,146 -30,146 -11,118 -11,118 -30))”.
- envlist – a list of environmental and contextual layers as colon separated short names. E.g. “bioclim_bio1:bioclim_bio12:bioclim_bio2:landuse”.
- txtTestPercentage - optional percentage of records dedicated to testing. E.g. “23”.
- chkJackKnife - optional parameter to enable/disable Jacknifing. E.g. “Y”.
- chkResponseCurves – optional parameter to enable/disable plots of response curves. E.g. “Y”.
- removedspecies - optional parameter to remove species from the analysis. Typically used to remove sensitive species that have been denatured.
- res - optional paramter to specify the resolution for the maxent model. Defaults to "0.01" when no value is provided.
Returns: analysis id. E.g. “123”.
- Classification (ALOC)
Start ALOC /alaspatial/ws/aloc, POST request. E.g. http://spatial.ala.org.au/alaspatial/ws/aloc
Parameters:- gc - number of groups to try and produce. No guarantee that convergence to the exact number will occur. If not, it will generate as close a number of groups as possible. E.g. “20”.
- area - bounding area in Well Known Text (WKT) format. E.g. “POLYGON((118 -30,146 -30,146 -11,118 -11,118 -30))”.
- envlist – a list of environmental layers as colon separated short names. E.g. “bioclim_bio1:bioclim_bio12:bioclim_bio2”.
- res - optional paramter to specify the resolution for the maxent model. Defaults to "0.01" when no value is provided.
Returns: analysis id. E.g. “123”.
- Generalized dissimilarity modelling (GDM)
GDM is split into 2 seperate steps. The first step generates a set of possible thresholds for site pairs. The second step takes the selected threshold and finishes the process
Start GDM /alaspatial/ws/gdm/step1, POST request. E.g. http://spatial.ala.org.au/alaspatial/ws/gdm/step1
Parameters:- speciesdata - A comma separated set of species data. Header: Longitude, Latitude, SpeciesIndex
- area - bounding area in Well Known Text (WKT) format. E.g. “POLYGON((118 -30,146 -30,146 -11,118 -11,118 -30))”.
- envlist – a list of environmental layers as colon separated short names. E.g. “bioclim_bio1:bioclim_bio12:bioclim_bio2”.
- res - optional paramter to specify the resolution for the maxent model. Defaults to "0.01" when no value is provided.
Returns: analysis id and a threshold in a CSV format.
Step 2: /alaspatial/ws/gdm/step2, POST request. E.g. http://spatial.ala.org.au/alaspatial/ws/gdm/step2
Parameters:- pid - A unique ID generated in Step 1
- cutpoint - The threshold value generated in Step 1 and selected by the user.
- useDistance - Use geographic distance as additional predictor.
- weighting - How the sites weighted (either equally (0) or by number of species (1)).
- useSubSample - Sample size.
- sitePairsSize - Set if 'useSubSample' is set to true .
Returns: analysis id with which you can pull up the generated data and information.
- Sites by Species, Occurrence density, Species richness
Start with /alaspatial/ws/sitesbyspecies, POST request. E.g. http://spatial.ala.org.au/alaspatial/ws/sitesbyspecies
Parameters, must include at least one of the optional "Types" parameters:- speciesq - The query to perform to get the species data from the biocache. E.g. “genus:Macropus”.
- qname - Data name that appears in the output. E.g. “Macropus”.
- area - Bounding area in Well Known Text (WKT) format. E.g. “POLYGON((118 -30,146 -30,146 -11,118 -11,118 -30))”.
- bs - The URL to the biocache service. E.g "http://biocache.ala.org.au/ws"
- gridsize - Size of output grid cells in decimal degrees. E.g. "0.1"
- movingaveragesize - Size of output moving average window for occurrence density and species density layers. E.g. for a 9x9 grid cell window use "&movingaveragesize=9"
- areasqkm - (optional) the total squre km area represented by the WKT on the area. This param is only used in the metadata.
- Types:
- sitesbyspecies - (optional) Include this parameter to produce a sites by species list. E.g. "&sitesbyspecies=1"
- occurrencedensity - (optional) Include this parameter to produce an occurrence density layer. E.g. "&occurrencedensity=1"
- speciesdensity - (optional) Include this parameter to produce a species richness layer. E.g. "&speciesdensity=1"
Returns: analysis id. E.g. “123”.
- Monitor Analysis
- /alaspatial/ws/job?pid=<analysis id> - returns the status and progress of a job.
E.g. http://spatial.ala.org.au/alaspatial/ws/jobs/state?pid=123
state - will be either "WAITING", "RUNNING", "SUCCESSFUL", "FAILED", "CANCELLED". When it is "SUCESSFUL" the results can be retrieved. - /alaspatial/ws/jobs/inputs?pid=<analysis id> - lists the inputs that have been supplied to the job
- /jobs/cancel?pid=<analysis id> - cancel a job based on the PID . E.g. http://spatial.ala.org.au/alaspatial/ws/jobs/cancel?pid=123
returns nothing if successful or "job does not exist"
- /alaspatial/ws/job?pid=<analysis id> - returns the status and progress of a job.
E.g. http://spatial.ala.org.au/alaspatial/ws/jobs/state?pid=123
- Retrieving Results
- /alaspatial/ws/download/<analysis id>. E.g. . E.g. http://spatial.ala.org.au/alaspatial/ws/download/123
downloads the zipped output of "SUCCESSFUL" analysis. - ALOC WMS service for the layer is /geoserver/wms?service=WMS&version=1.1.0&request=GetMap&layers=ALA:aloc_<analysis id>&styles=alastyles&FORMAT=image%2Fpng.
E.g. http://spatial.ala.org.au/geoserver/wms/reflect?layers=ALA:aloc_123&height=200&width=200 - Maxent WMS service for the layer is /geoserver/wms?service=WMS&version=1.1.0&request=GetMap&layers=ALA:species_<analysis id>&styles=alastyles&FORMAT=image%2Fpng.
E.g. http://spatial.ala.org.au/geoserver/wms/reflect?layers=ALA:species_123&height=200&width=200 - Occurrence Density WMS service for the layer is /geoserver/wms?service=WMS&version=1.1.0&request=GetMap&layers=ALA:odensity_<analysis id>&styles=alastyles&FORMAT=image%2Fpng.
E.g. http://spatial.ala.org.au/geoserver/wms/reflect?layers=ALA:odensity_123&height=200&width=200 - Species Richness WMS service for the layer is /geoserver/wms?service=WMS&version=1.1.0&request=GetMap&layers=ALA:srichness_<analysis id>&styles=alastyles&FORMAT=image%2Fpng.
E.g. http://spatial.ala.org.au/geoserver/wms/reflect?layers=ALA:srichness_123&height=200&width=200
- /alaspatial/ws/download/<analysis id>. E.g. . E.g. http://spatial.ala.org.au/alaspatial/ws/download/123