SpeciesObservationService

Last changed: 28 February 2017

About SwedishSpeciesObservationService

The web service is platform-independent. It means it can be used by any computer operating system and clients can be created in any computer language and tools that support SOAP.

SwedishSpeciesObservationService is one of the web services in ArtDatabankenSOA.

Available types of data

Species observation

Observations of species in nature. Several of the participants in Swedish LifeWatch will provide species observations in the future.

Reference documentation

Detailed documentation availble online on address: https://doc.artdatabankensoa.se/WebService

Namespaces that describes the web service SwedishSpeciesObservationService:

  • SwedishSpeciesObservationService contains definition of the web service interface.
  • ArtDatabanken.WebService.Data defines structure of data that web service uses.

Web service status

Current status for SOAP based web services can be viewed in the webb application WebAdministration.

Client data layer

Swedish Species Information Center has created a client data layer for internal use. Those who want to use the web services in ArtDatabankenSOA may choose to use our client data layer. This client data layer is plattform specific and uses Microsoft .NET Framework version 3.5. The data layer consists of some Dynamic-link libraries (DLL) and can be downloaded from the following link:

It is optional but recommended to use this client data layer. Last update of these dll's was done 2017-01-30.

Benefits when using the client data layer

  • Object oriented: Web services are not object oriented but the client data layer is.
  • Hides communication: Communication is handled by the client data layer.
  • Efficiency: Client data layer handles data efficiently, for example with the help of caching.
  • Shorter development time: A lot of code are already created and tested.

SwedishSpeciesObservationService can be used together with the client data layer.

Species observation data format

Two different data formats are used for species observations:

  • Darwin Core 1.5 compatible format.
  • Flexible species observation format.

These two formats have different advantages and disadvantages and are used in different situations.

Darwin Core 1.5 compatible format

This format is easier to use but it does not offer the same flexibility. All information (related to this data type) are returned for each species observation. One can not choose to retrieve only part of the information or additional information about the species observations. The claim that the format is compatible with Darwin Core 1.5 does not mean that is uses the same xml schema as Darwin Core 1.5 but all terms listed in Darwin Core 1.5 has a counterpart in this format. There are also some additional terms that do not have their counterparts in Darwin Core 1.5.

Class diagram for Darwin Core compatible format. See reference documentation for further details.

Flexible species observation format

This format is 100% flexible. Species observation data providers can use this format to deliver structured data related to species observations that is provider specific. User of species observation data can use this format to adjust returned information to their own needs. Information returned to user can be anything from a single field for each species observation to all fields for all requested species observation even if requested species observations contains different sets of data.

The flexible species observation format uses grouping of data related to species observation into abstract classes and properties. These abstract classes and properties may be either predefined or flexibly defined. Predefined species observation classes are the classes listed in the enum SpeciesObservationClassId. Examples of abstract predefined classes are Taxon, Location and Identification. Predefined species observation properties are the properties listed in the enum SpeciesObservationPropertyId. Flexibly defined species observation classes or properties uses an identifier that defines the class or property. Flexibly defined species observation properties may be used together with predefined species observation classes. The predefined abstract species observation class SpeciesObservation contains information about the species observation itself. All other abstract species observationen classes are considered as contained in the class SpeciesObservation. Predefined species observation classes and properties covers all fields in Darwin Core 1.5. Use of predefined species observation classes and properties are encouraged. Handling of data that belongs to predefined species observation classes and properties are easier to optimize than flexibly defined data.

Logical structure of abstract species observation classes. The class Etc is not a real abstract species observation class. It only indicates that more classes exists and all of them are located on this level.

Predefined abstract species observation classes together with expected properties: A * after the name indicates that the class or property is not part of Darwin Core 1.5.

  • SpeciesObservation: AccessRights, BasisOfRecord, BibliographicCitation, CollectionCode, CollectionID, DataGeneralizations, DatasetID, DatasetName, DynamicProperties, Id*, InformationWithheld, InstitutionCode, InstitutionID, Language, Modified, Owner*, OwnerInstitutionCode, References, ReportedBy*, ReportedDate*, Rights, RightsHolder, SpeciesObservationURL*, Type, ValidationStatus*.
  • Conservation*: ActionPlan*, ConservationRelevant*, Natura2000*, ProtectedByLaw*, ProtectionLevel*, RedlistCategory*, SwedishImmigrationHistory*, SwedishOccurrence*.
  • Event: Day, End*, EndDayOfYear, EventDate, EventID, EventRemarks, EventTime, FieldNotes, FieldNumber, Habitat, Month, SamplingEffort, SamplingProtocol, Start*, StartDayOfYear, VerbatimEventDate, Year.
  • GeologicalContext: Bed, EarliestAgeOrLowestStage, EarliestEonOrLowestEonothem, EarliestEpochOrLowestSeries, EarliestEraOrLowestErathem, EarliestPeriodOrLowestSystem, Formation, GeologicalContextID, Group, HighestBiostratigraphicZone, LatestAgeOrHighestStage, LatestEonOrHighestEonothem, LatestEpochOrHighestSeries, LatestEraOrHighestErathem, LatestPeriodOrHighestSystem, LithostratigraphicTerms, LowestBiostratigraphicZone, Member.
  • Identification: DateIdentified, IdentificationID, IdentificationQualifier, IdentificationReferences, IdentificationRemarks, IdentificationVerificationStatus, IdentifiedBy, TypeStatus, UncertainDetermination*.
  • Location: Continent, CoordinateM*, CoordinatePrecision, CoordinateSystemWkt*, CoordinateUncertaintyInMeters, CoordinateX*, CoordinateY*, CoordinateZ*, Country, CountryCode, County, DecimalLatitude, DecimalLongitude, FootprintSpatialFit, FootprintSRS, FootprintWKT, GeodeticDatum, GeoreferencedBy, GeoreferencedDate, GeoreferenceProtocol, GeoreferenceRemarks, GeoreferenceSources, GeoreferenceVerificationStatus, HigherGeography, HigherGeographyID, Island, IslandGroup, Locality, LocationAccordingTo, LocationID, LocationRemarks, LocationURL*, MaximumDepthInMeters, MaximumDistanceAboveSurfaceInMeters, MaximumElevationInMeters, MinimumDepthInMeters, MinimumDistanceAboveSurfaceInMeters, MinimumElevationInMeters, Municipality, Parish*, PointRadiusSpatialFit, StateProvince, VerbatimCoordinates, VerbatimCoordinateSystem, VerbatimDepth, VerbatimElevation, VerbatimLatitude, VerbatimLocality, VerbatimLongitude, VerbatimSRS, WaterBody.
  • MeasurementOrFact: MeasurementAccuracy, MeasurementDeterminedBy, MeasurementDeterminedDate, MeasurementID, MeasurementMethod, MeasurementRemarks, MeasurementType, MeasurementUnit, MeasurementValue.
  • Occurrence: AssociatedMedia, AssociatedOccurrences, AssociatedReferences, AssociatedSequences, AssociatedTaxa, Behavior, CatalogNumber, Disposition, EstablishmentMeans, IndividualCount, IndividualID, IsNaturalOccurrence*, IsNeverFoundObservation*, IsNotRediscoveredObservation*, IsPositiveObservation*, LifeStage, OccurrenceID, OccurrenceRemarks, OccurrenceStatus, OccurrenceURL*, OtherCatalogNumbers, Preparations, PreviousIdentifications, Quantity*, QuantityUnit*, RecordedBy, RecordNumber, ReproductiveCondition, Sex, Substrate*.
  • Project*: IsPublic*, ProjectCategory*, ProjectDescription*, ProjectEndDate*, ProjectID*, ProjectName*, ProjectOwner*, ProjectStartDate*, ProjectURL*, SurveyMethod*.
  • ResourceRelationship: RelatedResourceID, RelationshipAccordingTo, RelationshipEstablishedDate, RelationshipOfResource, RelationshipRemarks, ResourceID, ResourceRelationshipID.
  • Taxon: AcceptedNameUsage, AcceptedNameUsageID, Class, DyntaxaTaxonID*, Family, Genus, HigherClassification, InfraspecificEpithet, Kingdom, NameAccordingTo, NameAccordingToID, NamePublishedIn, NamePublishedInID, NamePublishedInYear, NomenclaturalCode, NomenclaturalStatus, Order, OrganismGroup*, OriginalNameUsage, OriginalNameUsageID, ParentNameUsage, ParentNameUsageID, Phylum, ScientificName, ScientificNameAuthorship, ScientificNameID, SpecificEpithet, Subgenus, TaxonConceptID, TaxonConceptStatus*, TaxonID, TaxonomicStatus, TaxonRank, TaxonRemarks, TaxonSortOrder, TaxonURL*, VerbatimScientificName*, VerbatimTaxonRank, VernacularName.

All providers of species observations must also provide meta data about these abstract species observation classes and properties. Separate methods (in contrast to methods related to the retrieval of species observations) are used to retrieve this meta data.

A species observation contains species observation fields. Each field contains information about the value but also information about which species observation class and property that the field belongs to. The properties Class, ClassIndex, IsClassIndexSpecified, IsPropertyIndexSpecified, Property and PropertyIndex in class WebSpeciesObservationField defines which species observation class and property that the field belongs to. Properties Information, Locale, Type, Unit and Value in class WebSpeciesObservationField contains information related to the actual value of the field.

Class diagram for flexible species observation format. Explanation of the different classes and enums:

  • WebSpeciesObservation: Information about one species observation is contained in a WebSpeciesObservation instance. How much information that a WebSpeciesObservation contains depends on context, how much information that was requested and how much information that is available.
  • WebSpeciesObservationField: One instance of WebSpeciesObservationField contains one pice of data related to a species observation. Properties Class and Property specifies which value this field contains. Property ClassIndex is used when one species observation can have values ​​for multiple instances of species observation classes. Property PropertyIndex is used when one species observation class can have multiple values for one species observation property. For example if information about one observer is represented as a species observation class must property ClassIndex be used to distinguish between different observers.
  • WebSpeciesObservationClass: An instance of WebSpeciesObservationClass defines which species observation class that is referenced.
  • WebSpeciesObservationProperty: An instance of WebSpeciesObservationProperty defines which property in a species observation class that is referenced.
  • SpeciesObservationClassId: This is an enumeration of predefined species observation classes.
  • SpeciesObservationPropertyId: This is an enumeration of predefined species observation properties.

See reference documentation for further details.

Technical details about the web service

Language handling

The interface to SwedishSpeciesObservationService is prepared for multi language handling but currently only swedish are supported.

Protocols

All web services in ArtDatabanken SOA support both SOAP 1.1 and SOAP 1.2. For efficiency reasons Swedish Species Information Center uses a Microsoft specific binary format for internal use. All web services have three endpoints that supports the three different protocols.

WSDL description of a web services can be retrived by adding ?wsdl to the base address of the web service. For example https://SwedishSpeciesObservation.ArtDatabankenSOA.se/SwedishSpeciesObservationSOAPService.svc?wsdl.

Transaction handling

SwedishSpeciesObservationService does not modify any data so it needs no transaction handling.

User session

A user must login to SwedishSpeciesObservationService before any other methods in the web service are called. Login is made by a call to the Login method which on successful login returns a security token in property WebLoginResponse.Token. This security token must be keept by the client application and is provided in property WebClientInformation.Token in further calls to the web service. When the user has finished using the the web service a call to the method Logout should be made.

 


Contact

Björn Karlsson, System developer
The Swedish Species Information Centre, SLU
bjorn.karlsson@slu.se, 018-672679