Developer Guide - Office of Environment and Heritage
Contents
1. hee Ae acca ET 6 3 1 BioNet Web Services URI iiss scatinsniensevens iv scadacenetievevisiedictceensacindadinnnsddes 6 3 2 AICHILECTULES cccacccesecescetaiss tea aae e E A aE a E aa aaa 6 3 3 Reference material for developers ccccccecceessseeenececeeeeeeteseeeeeeeeeeees 6 as e a o E ashes sate ct ade este erat A eee 8 4 1 Sample OD ata queries ca ceee swt tats degree seh iene 8 4 2 Sample OData Clee ys siccds ce vayatceceicencicenatceaccintas dene deesscctapaveaseaee dacencsensuueeers 8 4 2 1 CRANE naat cls Adee Rn A 8 4 2 2 HT MLS amp JavaScript siccdessnsencahecivensiaeisteeeetancettentitesateeemkeenss setae 9 4 3 Sample OUP U a des elds eal a a cavsenetieees ys eiue a AS A EAE 9 5 Data We CONMOCU is iscscicsvcsssseesvevedecvcsucvccvaessvsesssuateadedusdesvatsavensartivertddaedetesaedisisaeatetesis 11 BioNet Web Services Developer Guide v 1 Introduction BioNet is the trusted source of biodiversity data for the state of NSW and a resource for all The BioNet Web Service provides an application level publically available API enabling developers to directly integrate biodiversity data into their software systems and unlock the innovation potential of this valuable data set What data is available Release 1 of the BioNet Web Services makes all of the species sightings records available via the API This is the same data that is currently available through the BioNet Atlas of NSW Wildlife The data available via the2. Environment and Heritage ownerInstitutionCode Office of Environment and Heritage associatedReferences null countryConservation null catalogNumber 75080 035 consequence null establishmentMeans Alive in NSW Native estimateTypeCode null individualCount null individualID null observationType Observed occurrenceID urn catalog NSW Office of Environment and Heritage BioNet Atlas of NSW Wildlife 75080 035 occurrenceRemarks occurrenceRemarks withheld occurrenceStatus Present otherCatalogNumbers null PNFFilter N recordedBy HUTKE recordNumber null reproductiveCondition null sex null stateConservation Protected status Va lid and accepted without modification eventDate 1983 09 06 eventID null eventRemarks null eventTime null habitat null samplingEffort null samplingProtocol null coordinatePrecision 9 coordinateUncertaintyInMeters 1000 0000 country Australia countryCode AU county BEGA VALLEY decimalLatitude 37 246482589 decimalLongitude 149 921284892 easting 759113 geodeticDatum GDA94 georeferenceProtocol null locality locality withheld locationRemarks locationRemarks withheld mapSheetNumber 8823 EDEN maximumElevationInMeters null minimumElevationInMeters null northing 5873784 stateProvince NSW z
3. MA Sydney select countryConservation amp filter countryConservation ne null amp count true select decimalLatitude decimalLongitude amp filter contains dynamicProperties CMA North ern Rivers filter PNFFilter eq Y amp select catalogNumber recordNumber scientificNamelD scientificName vernacularNam e PNFFilter amp orderby scientificNamelD select catalogNumber scientificNamelD scientificName vernacularName PNFFilter decim alLatitude decimalLongitude geodeticDatum amp filter decimalLongitude ge 142 0 and decimalLongitude le 142 5 and decimalLatitude It 32 000000001 and decimalLatitude gt 32 499999999 amp orderby scientificNamelD 4 2 Sample OData client 4 2 1 C NET Resources e http www nuget org packages Microsoft OData Client e https visualstudiogallery msdn microsoft com 9b786c0e 79d1 4a50 89a5 125e57475937 Sample C snippet BioNet Web Services Developer Guide 8 Uri svcURL new Uri ConfigurationManager AppSettings metadataURL ToString ODataServicesTestingApp Default Container container new ODataServicesTestingApp Default Container svcURL if string IsNullOrEmpty ODataQuery Text Trim string queryString string Format SpeciesSightings 0 ODataQuery Text Trim dataGridView1 DataSource container Execute lt TbICUBE_SpeciesSightings gt new Uri queryString UriKind Relative ToList 4 2 2 HTML5 amp JavaScript Resources e http codes
4. OVide 00 2 eee cecceeeeeeeeeeeeeeeeeeeeeeeneeeeeeeeaaeeeeesetaaeeeeenaas 2 2 3 Whatis YOUR SLA perni apea a e EEE aE REA EAEE ERER E TaESA 2 2 4 Where do find documentation on the OData protocol eeee 2 2 5 Where do find documentation on the data available via the Biodiversity Web SOMICES 2 civitinkasetsstiasantnsswrtsaticntudaan deiatigridutehuninitnsssexal E 2 2 6 Are there any security restrictions placed on the data ccceceeeeee 3 2 7 Are there any restrictions on your implementation of OData that should beaa e Oi a tastvinatansnoorelinielbovsadesnaesu eubin edad aE A a E E E 3 2 7 1 Sopderby query OPLION iiaei asi aana ia E eavet 3 2 7 2 ANY and all FUNCTIONS ccccccecsessesseeeeeeceeceeeeeeeeeeeeceesaeaeaeeeeeeeseeeees 4 2 7 3 Filtering Of navigation properties eect e eter eeeeeetaaaeeeeeeeeeeeead 4 2 7 4 Server side queryable attributes eccceeesseceeeeeeeeeeeeeeeeeeeeeteneeeeees 4 2 8 What best practice guidance should be aware of when creating OData queries 4 2 8 1 Sfilter operators aes sssaweieivedasdascsceavacaaebavves souatanhecdaniisandeaseiedidaresieurnes 4 2 8 2 Sorderby query OPTION seregei sane aa aeaaee STan 4 2 9 Which fields should my query tarQet 0 cccccccceeeeeeeeeeeeeeteeeeeeenaeeeeeeeaes 4 2 10 How should acknowledge the use of the BioNet Web Services in my ete 8 072 12 Eae ela re ne eve eee ore ee E eee meee meee 5 oo Getting Stanted 2222s tee
5. RAG W Office of ev Environment GOVERNMENT X Heritage BioNet Web Services Developer guide Version 2 0 BioNet Web Services Developer Guide iii 2015 State of NSW and Office of Environment and Heritage With the exception of photographs the State of NSW and Office of Environment and Heritage are pleased to allow this material to be reproduced in whole or in part for educational and non commercial use provided the meaning is unchanged and its source publisher and authorship are acknowledged Specific permission is required for the reproduction of photographs The Office of Environment and Heritage OEH has compiled this guide in good faith exercising all due care and attention No representation is made about the accuracy completeness or suitability of the information in this publication for any particular purpose OEH shall not be liable for any damage which may occur to any person or organisation taking action or not on the basis of this publication Readers should seek appropriate advice when applying the information to their specific needs This document may be subject to revision without notice and readers should ensure they are using the latest version All content in this publication is owned by OEH and is protected by Crown Copyright It is licensed under the Creative Commons Attribution 4 0 International CC BY 4 0 subject to the exemptions contained in the licence The legal code for the licence is available a
6. a and your development platform to find specific reference material if available for your project e About OData o http www software architects com devblog 2014 09 12 10 OData FAQs e OData tutorials http www odata org getting started basic tutorial https damienbod wordpress com 2014 07 09 web api odata v4 using an odata t4 generated client part 8 o http ologs msdn com b odatateam archive 2014 03 1 1 how to use odata client code generator to generate client side proxy class aspx BioNet Web Services Developer Guide 6 v4 create an odata v4 client app o http help sap com saphelp hanaplatform helpdata en 8d 78eb6f6e8f4307be939 a6bc684b9ca content htm o http www ibm com developerworks data library techarticle dm 1205odata index html o http www oracle com webfolder technetwork tutorials obe db dotnet EntityFrame workWCF WCEEntityFramework htm e OData libraries amp code http www odata orq libraries http stackoverflow com but make sure you use only approved solutions http ologs msdn com b odatateam https components xamarin com gettingstarted simple odata client http www pluralsight com courses table of contents odata clients https msdn microsoft com en us library ff478141 aspx e Vendor products supporting OData http www odata org ecosystem http www odata orq libraries http stackoverflow com but make sure you use only approved solutions http ologs msdn com b od
7. atateam https components xamarin com gettingstarted simple odata client http Awww pluralsight com courses table of contents odata clients httos msdn microsoft com en us library ff478141 aspx e Vendor products supporting OData o http www odata org ecosystem O O O O O 0 O O O O O 0 0 BioNet Web Services Developer Guide 7 4 Samples 4 1 Sample OData queries This link provides the structure information https data bionet nsw gov au biosvcapp odata metadata Calling the SpeciesSightings service returns the first 1000 rows of the dataset All queries return data paged at 1000 rows at a time the NEXT link is at the bottom of the output https data bionet nsw gov au biosvcapp odata SpeciesSightings CoreData Server side queryable attributes Note this list is not exhaustive For a full list of attributes use the metadata query link above select dynamicProperties filter catalogNumber eq 065000001 select catalogNumber scientificName vernacularName filter contains vernacularName River Red filter contains vernacularName River Red amp count true filter startswith vernacularName Red filter startswith toupper vernacularName RED filter endswith scientificName camaldulensis filter indexof vernacularName blue gt 1 select dynamicProperties amp filter contains dynamicProperties CMA Northern Rivers select dynamicProperties amp filter contains dynamicProperties C
8. catalogNumber scientificNamelD consequence locationID PNFFilter occurrenceStatus taxonRank stateProvince coordinatePrecision datasetID occurrencelD BioNet Web Services Developer Guide 3 2 5 2 any and all functions The any and a11 functions have been disabled to mitigate the risk of slow query performance and enable the service to enforce the Page limits This will not restrict the data that a user can extract rather it limits data served to 1 000 rows per page 2 5 3 Filtering of navigation properties Support for filtering on navigation properties will not be implemented Filtering on navigation properties can result in a join which will impact on the performance of the service This will not affect the usability of the service for users as the underlying data model does not support this type of filtering 2 5 4 Server side queryable attributes We have implemented server side queryable attributes to safe guard against large data returns and provide query optimisations The attributes that have been implemented include e PageSize 1000 e MaxNodeCount 50 2 6 What best practice guidance should be aware of when creating OData queries 2 6 1 Sfilter operators The best practice is to use the eq operator in preference to other operators such as startswith or endswith This is because the eq operator is the most efficient from a server resource consumption point of view and will help ensure that performance of the s
9. ervice remains high for all users For example if you know you are searching for Square tailed Kite you should use Sfilter vernacularName eq Square tailed Kite The contains operator should be avoided as this operator is very resource intensive and can result in query time outs In this case it would be preferable to use the startswith operator 2 6 2 Sorderby query option The Sorderby query option sorts result returned in either descending or ascending order Best practice is to not use this option and undertake sorting if needed on the client side in your application However if sorting on the server side is require it should be noted that ordering is very resource intensive and can result in query time outs In this instance best practice is to combine the Sorderby with a filter operator to limit the result set that is being sorted In testing it was found that sorting result sets of 500 000 records performed acceptably For example filter vernacularName eq Square tailed Kite amp Sorderby locationID desc Which fields should my query target The eq operator can be used on any field The following fields have been tuned to enable their use with the startswith endswith and contains operators if necessary BioNet Web Services Developer Guide 4 e scientificName e vernacularName e family e datasetName e county The dynamicProperties field must not be used for querying The field is
10. gov au What is your SLA Our target for the web service is to support 50 simultaneous connections and process a well formed request within one second of the web service receiving the request The service will be unavailable from 3am to 5am to allow us to run the daily data update For more details on a well formed request see sections 2 6 What best practice guidance should be aware of when creating OData queries and 2 9 Which fields should my query target 2 3 Where do find documentation on the OData protocol The service uses the OASIS OData v4 0 Protocol Documentation on the protocol is available at OData 2 3 1 Where do find documentation on the data available via the Biodiversity Web Services Release 1 0 of the BioNet Web Services implements the Species Sighting Web Service The data available via this service is documented in the BioNet Species Sighting Web Service Data Standard which is available at BioNet for developers BioNet Web Services Developer Guide 2 The data standard provides the following information o Field name o Definition o Example o Data Type o Access Restrictions o An indication whether data is always present in that field 2 3 2 Are there any security restrictions placed on the data Yes the web service implements and uses the existing security model applied to the BioNet Atlas of NSW web application For more details on the levels of access please refer to section 3 of the BioNet A
11. martinc com 201 1 01 31 leveraging odata end points in json format with iquery e http www odata org libraries javascript 4 3 Sample output Fig 2 SpeciesSightings_CoreData record json format odata context http webdev environment nsw gov au BioSvcApp odata metadata tSpeciesSightings_CoreData value PKID 36438659 basisOfRecord HumanObservation collectionCode BioNet Atlas of NSW Wildlife dataGeneralizations The observer name has been changed to a unique User ID datasetID 1 datasetName OEH Default Sightings dcterms_bibliographicCitation BioNet Atlas of NSW Wildlife 28 04 2015 12 00 AM dcterms_langu en determs_modified 1996 1 1T00 00 00 is Jan 1 1996 12 00AM UTC dceterms_right Creative Commons by Attribution dcterms_rightsHolder Office of Environment and Heritage dceterms_type Event dynamicProperties BFMCS N A botanicalDivision N A CMA Southern Rivers CMAsubregion Southern Rivers East Gippsland Lowlands Part C floraReserve N A geogExtent N A IBRA South East Corner NSW mechanicalHRDescription N A potentiallmpact N A profileID N A reserve N A speciesFireDescription N A stateForest N A vulnerability N A informationWithheld The following fields have been withheld and are only available to licensed or OEH staff locality locationRemarks occurrenceRenarks institutionCode NSW Office of
12. one 55 class Aves family Meliphagidae genus Caligavis infraspecificEpithet null kingdom Fauna nomenclaturalCode ICZN order Passeriformes populationName null scientificName Caligavis chrysops scientificNameAuthorship Latham 1802 scientificNameID 0614 sortOrder 2638 locationID 2620 035 specificEpithet chrysops taxonRank Species vernacularName Yellow faced Honeyeater J H Fig 3 SpeciesSightings_MeasurementsOrFacts record json format BioNet Web Services Developer Guide 9 odata context http webdev environment nsw gov au BioSvchpp odata SmetadatatMeasurementOrFact value DatasetID 1 OccuranceID urn catalog Office of Environment and Heritage Department of Planning and Environment representing the State of New South Wales BioNet Atlas of NSW Wilidilife 065000001 measurementID 405 measurementT ype SurfaceGeology measurementValue BA measurem entUnit Basalt BioNet Web Services Developer Guide 10 5 Data we collect The service logs request details for internal analytics usage The following information is captured e Web Service Name e Request parameters e Date amp Time of request e Data Size of response e Geographic Location of requestor e User name e Application name BioNet Web Services Developer Guide 11
13. t Creative Commons OEH asserts the right to be attributed as author of the original material in the following manner State of New South Wales and Office of Environment and Heritage 2015 Published by Office of Environment and Heritage 59 Goulburn Street Sydney NSW 2000 PO Box A290 Sydney South NSW 1232 Phone 61 2 9995 5000 switchboard Phone 131 555 environment information and publications requests Phone 1300 361 967 national parks general environmental enquiries and publications requests Fax 61 2 9995 5999 TTY users phone 133 677 then ask for 131 555 Speak and listen users phone 1300 555 727 then ask for 131 555 Email info environment nsw gov au Website www environment nsw gov au Report pollution and environmental incidents Environment Line 131 555 NSW only or info environment nsw gov au See also www environment nsw gov au ISBN 978 1 76039 081 5 OEH 2015 0548 August 2015 BioNet Web Services Developer Guide iv Contents Wee MATPOCUCUION isi ceccer T cece fects Saees decvendccessnesescatsceascicaccscascedsnuwstetestedssdnsteusee 1 1 1 What data is available ic wickstvcsteccniiusdeddataswetaaoens tes tavesuadasnandcaueececnentsge 1 23 Before VOU DOG I jccate stands teswecesetavevesaaverecoutsneweersussnekeutensas daD dusesaevasweuwenesnsauenscaweaseoss 2 2 1 How do go about developing an application using data from BioNet 2 2 2 What support do YOU Pr
14. tlas User Manual As the same model is used existing user credentials for the BioNet Atlas of NSW Wildlife web app will work for the Web Service New user credentials should also be requested via the existing application process for login access to the BioNet Atlas of NSW Wildlife However authentication is not mandatory If you do not pass a user name and password to the web service it will return the publicly available data as per the query submitted It should be noted that this data will contain obfuscated data for species listed in the Sensitive Species Policy This will be made clear in the dataGeneralizations field and will withhold some fields as listed in the dataWithheld field There are also records which we do not have permission to share publically These are withheld and will not appear in the data returned 2 4 Are there any terms and conditions should be aware of when using data from the web service Yes details of the terms and conditions are available and should be read and accepted before development of your application Development of an application that uses data via the web service will be considered acceptance of the terms and conditions by the developer of the application 2 5 Are there any restrictions on your implementation of OData that should be aware of 2 5 1 Sorderby query option To prevent sorting on properties that are not indexed in the database orderby has been restricted to the following fields
15. used to pass additional information which does not fit in the Darwin Core Standard and is intended for client side processing 2 7 How should acknowledge BioNet Web Services in my application Please contact us for a logo that you can use in your application to acknowledge the source of the data BioNet Web Services Developer Guide 5 3 Getting started Make sure you have received your App Token before proceeding further See Section 2 1 How do go about developing an application using data from BioNet for more about the App Token 3 1 BioNet Web Services URI https data bionet nsw gov au biosvcapp odata 3 2 Architecture All requests are made using https to the relevant service URI BioDiversity Web Services Figure 1 Service architecture 1 HTTPS request with App Token in header Request also conforms to REST OData protocol 2 Web service processes request and sends response in json format No other formats are support at this time 3 OData response contains results Results are paged at 1000 rows per page with a NEXTLINK link embedded in the data Note that this only occurs if the resultant record count is greater than 1000 For example odata nextLink https data bionet nsw gov au biosvcapp odata SpeciesSightings _CoreData skip 1000 3 3 Reference material for developers The following material is given to get you started Please note that it is not exhaustive It is suggested you Google ODat
16. web service is updated daily from the source data which is held in the BioNet Atlas of NSW Wildlife BioNet Web Services Developer Guide 1 2 Before you begin This section contains important information you need to understand and consider before you start the development of your application 2 1 How do go about developing an application using data from BioNet Download and fill out the Data Use Case form from BioNet for developers and submit to bionet environment nsw gov au We will use the information provided to support you through the process and to issue you with an App Token Once you have received your App Token read this guide and start developing 2 2 What support do you provide We will provide advice to help guide you in your development decision making particularly around the use and interpretation of data made available via the service This advice will be provided based on the information you supply us in the Data Use Case form We will provide technical support for the server side services that is for the correct functioning and availability of the API itself and for the data that is served through that API We do not provide technical support for client side applications development toolkits or libraries Support of these should be sourced from the vendor supplier of the software or in the case of open source solutions from the developer community For support email bionet environment nsw
Download Pdf Manuals
Related Search