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
  • 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/
      Example: {"wkt": "POLYGON((125.5185546875 -21.446934836644,128.2431640625 -21.446934836644,128.2431640625 -19.138942324356,125.5185546875 -19.138942324356,125.5185546875 -21.446934836644))", "name": "test", "description": "test description", "userid": "user1"} Return value: a JSON object containing the pid for the newly uploaded geometry e.g. {"pid":3742602}
    • 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/
      Example: {"geojson": "{\"type\":\"Polygon\",\"coordinates\":[[[125.5185546875,-21.446934836644001],[128.2431640625,-21.446934836644001],[128.2431640625,-19.138942324356002],[125.5185546875,-19.138942324356002],[125.5185546875,-21.446934836644001]]]}", "name": "test", "description": "test", "userid": "user1"} Return value: a JSON object containing the ID for the newly uploaded geometry e.g. {"id":3742602}
    • 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/
      Return value: a JSON object containing the ID for the newly uploaded geometry e.g. {"id":3742602}
    • Upload geometry from shape file feature.This is a two step process:
      1. 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/
        Return value: Both methods return a json object with a field "shp_id" whose value is an id for the uploaded shape. In addition, the object contains numbered fields for each feature whose values are the attribute values for each feature. E.g. {"shp_id":"1376461253025-0","0":{"id":15,"name":"Snow and ice"}}
      2. 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/
        Return value: a JSON object containing the ID for the newly created object e.g. {"id":3742602}
    • 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/
      Return value: a JSON object containing a boolean field "updated" which indicates whether or not the object was successfully updated e.g. {"updated":true}
  • 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
      Return value: a JSON object containing the id for the newly created point of interest e.g. {"id":1234}
    • 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
      Not supplying values for optional fields will have the effect of nulling any previously set values for such fields. Return value: a JSON object containing a boolean field "updated" which indicates whether or not the point of interest was successfully updated e.g. {"updated":true}
    • 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
  • Search
  • 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)
  • Tabulation
  • RIF-CS

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”.
      • List of analysis valid environmental layer short names here. These are a subset of all layers here
      • List of analysis valid contextual layers; landcover, landuse, vast, native_veg, present_veg
    • 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”.
      • List of analysis valid environmental layer short names here. These are a subset of all layers here
      • List of analysis valid contextual layers; landcover, landuse, vast, native_veg, present_veg
    • 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”.
      • List of analysis valid environmental layer short names here. These are a subset of all layers here
    • 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"

  • 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