Arterna.fi | Finlands Artdatacenter

Interfaces for software developers

Hello there!

Our APIs are currently in internal use only and will be released once they have been stabilized. For now this page is little more than a placeholder.

This page is available only in English.

Data warehouse: Background

We gather observation, collection specimen, literature, etc., etc. data from Finland and close by regions (and in case of collection specimens from all over the world) to a centralized Data warehouse for easy single place access.

The idea is to have at least the most basic information of each record (taxon, time, place (coordinates), person), but the warehouse can contain all the background variables for the record. For most variables the glossary has not yet been harmonized, but our aim is to provide reference glossaries for the most common variables. This is also called "master data management". See master data section for more details.

Data warehouse: Query service

In use but not yet public.

Data warehouse: Data transfer

There are two ways to get your data into the Data warehouse: Push and transaction feed. When pushing, when ever a record is stored, modified or deleted, the information is pushed to the Data Warehouse (You call us). This is a preferred method if it is desirable that the changes are visible in the Data warehouse almost instantly. The other method, transaction feed is suited for services that will be synchronized for example once a night. You provide a service that we read periodically (We call you).

Data PUSH

Not yet

Transaction feed

This service must be implemented in two parts: 1) ATOM transaction feed, 2) DarwinCore Recordset service

ATOM transaction feed

From time to time the Data warehouse contacts the data source. The response is a list of transaction events (inserts, updates and deletions). A sequence id or a timestamp is given as a parameter. In both cases, the response should contain those changes that have occurred from that sequence id or timestamp onward (inclusive).

The number of transactions included in the response should be limited to a maximum number (for example 1000). This limit can also be given as a parameter but to prevent DOS-attacks a hardcoded limit should always exist).

The transactions should be listed in ascending order (oldest first, newest last) in a way that if the limit is reached, the oldest transactions are shown.

Examples: GET: http://example.org/transactions?from=12345 - Should give all transactions that have sequence id 12345 or higher. Number of transactions shown is limited to maximum limit. Transaction 12345 should be the first entry of the transaction feed. GET: http://example.org/transactions?from=12345&limit=50 - Same as above, limited to 50 transactions. GET: http://example.org/transactions?timestamp=1337781842 - Same as in first request, except response should contain all transactions that have occured since the given EPOCH timestamp (inclusive). Example response: <?xml version='1.0' encoding='utf-8'?> <feed xmlns="http://www.w3.org/2005/Atom"> <author>Finnish Museom of Natural History</author> <id>5864CC51-D608-43AA-9DF6-EC0946341E40</id> <link>http://example.org/Balticdiversity?timestamp=1337781842</link> <title>Balticdiversity data exchange protocol feed</title> <updated>2012-05-23T13:40:21Z</updated> <entry> <id>5525715</id> <link rel="alternate" type="application/xml" href="http://example.org/records/JA.261340377" /> <title>JA.261340377</title> <updated>2012-05-23T10:25:22Z</updated> <summary>INSERT</summary> </entry> <entry> <id>5525716</id> <link rel="alternate" type="application/xml" href="http://example.org/records/JA.261340378" /> <title>JA.261340378</title> <updated>2012-05-23T10:25:30Z</updated> <summary>DELETE</summary> </entry> </feed>

None of the header fields (author, id, link, title, updated) are used for any real operational purposes. They are however required elements of the ATOM standard.

author: Freely chosen name for the provider of the feed id: Some id for the ATOM feed link: The query that resulted in this response updated: When the page was generated

Entries part is the important bit:

id: Transaction sequence ID link: Link to DarwinCore document of the record that was altered in this transaction (described in part 2) title: ID of the record (unique to your data source) updated: Time of the transaction (not used, but nice to have) summary: One of INSERT,DELETE,UPDATE (not used, but nice to have)

Transaction sequence ID starts from 1 and increases by one for each transaction.

For example: Transaction ID Record ID Summary 1 ABC.35211 INSERT 2 322fgGs INSERT 3 ABC.35211 DELETE 4 12345 UPDATE ...

Records are identified by an id which is unique for that data source. The IDs can be numerical or in any textual format, like a GUID, or a complete URI for the record. ID must be shorter than 200 characters.

DarwinCore Recordset service

DarwinCore recordset contains the relevant information about a single record.

Example request: GET: http://example.org/records/JA.261340377 Example response: <?xml version='1.0' encoding='utf-8'?> <SimpleDarwinRecordSet xmlns="http://rs.tdwg.org/dwc/xsd/simpledarwincore/" xmlns:dc="http://purl.org/dc/terms/" xmlns:dwc="http://rs.tdwg.org/dwc/terms/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://rs.tdwg.org/dwc/xsd/simpledarwincore/ http://rs.tdwg.org/dwc/xsd/tdwg_dwc_simple.xsd"> <SimpleDarwinRecord> <dwc:occurrenceID>JA.261340377</dwc:occurrenceID> <dc:modified>2012-05-22T21:00:00Z</dc:modified> <dwc:recordedBy>Piirainen, Esko</dwc:recordedBy> <dwc:basisOfRecord>HumanObservation</dwc:basisOfRecord> <dwc:scientificName>Carduelis carduelis</dwc:scientificName> <dwc:individualCount>2</dwc:individualCount> <dwc:eventDate>2013-06-20</dwc:eventDate> <dwc:country>Finland</dwc:country> <dwc:municipality>Helsinki</dwc:municipality> <dwc:locality>Myllypuro</dwc:locality> <dwc:decimalLatitude>60.225667</dwc:decimalLatitude> <dwc:decimalLongitude>25.068048</dwc:decimalLongitude> <dwc:coordinatePrecision>0.000000</dwc:coordinatePrecision> <dwc:geodeticDatum>WGS84</dwc:geodeticDatum> <dwc:associatedReferences>http://hatikka.fi/?page=view&source=2&id=1092226</dwc:associatedReferences> </SimpleDarwinRecord> </SimpleDarwinRecordSet> occurenceID: The id for this record. modified: When was the record last modified. Optional. recordedBy Who collected/reported this specimen/observation. Freely formated text. Optional. basisOfRecord: PreservedSpecimen, FossilSpecimen, LivingSpecimen, HumanObservation scientificName: The scientific name for this record using BALTICDIVERSITY taxonomy. individualCount: Number of specimens/observations. Optional. eventDate: When the specimen was collected, or bird observed, etc. country: Location of event. municipality: -"- locality: -"- decimalLat/Lon: WGS84 coordinates of the event. coordinatePrecision: Precision of the coordinates in decimals. For example lat/lon 60.0/20.0 and precision 0.5 define a bounding box 59.5-60.5/19.5-20.5 geodeticDatum: Always WGS84. associatedRefereces: Link to original datasource, showing more information about this specimen/observation. Optional.

In addition, you can include any Darwin Core terms you wish ,but they will not be used by the DW. (http://rs.tdwg.org/dwc/terms/index.htm)

If the record (identified by record id) does not exists (has been deleted), an empty SimpleDarwinRecordSet should be returned.