ArtenFinder Web Service API Version 2.0


Dokumentation der ArtenFinder REST Web-Service API Version 2.0

Version: 2.0.37

Copyright: © 2014 Struktur- und Genehmigungsdirektion Nord Rheinland-Pfalz

Aktualisierungsdatum: 10.03.2023


Verzeichnis


Allgemeines


Zeichenkodierung

Die REST-Schnittstelle antwortet in der Kodierung UTF-8.


Formate

Die REST-Schnittstelle beantwortet Anfragen in den Formaten XML, JSON oder JavaScript.


XML

Eine Antwort in XML kann für jede Anfrage an die REST-Schnittstelle über den URL-Parameter format und die Wertzuweisung xml angefordert werden. Geantwortet wird hieraufhin mit Content-Type: text/xml; charset=utf-8.


JSON

JSON ist das Standardausgabeformat der REST-Schnittstelle. Standardgemäss antwortet die Schnittstelle in Content-Type: application/json; charset=utf-8.


JavaScript

Die REST-Schnittstelle gibt für in JSON with padding (JSONP) angeforderte Antworten JavaScript zurück. Die Anforderung erfolgt über den URL-Parameter callback in dem der gewünschte Methodenname eingetragen wird. Beantwortet wird diese Anfrage mit Content-Type: application/javascript; charset=utf-8.

Neben Cross-Domain GET-Anfragen mittels JSONP bietet die REST-Schnittstelle für Schreiboperationen in JavaScript für die Methoden POST, PUT und DELETE Cross-Origin Resource Sharing (CORS) an. Beispiele zur Anwendung von Cross-Domain Schreiboperationen in JavaScript sind detailliert im jeweiligen Abschnitt dokumentiert.


Authentifizierung für zugriffsbeschränkte Anfragen

Die Nutzer-Authentisierung der REST-Schnittstelle erfolgt einheitlich für die Methoden GET, POST, PUT und DELETE. Zusätzlich zur jeweiligen Anfrage sind hierfür zwei Header erforderlich, X-Auth-User und X-Auth-Token, Platzhalter für den Loginnamen des Nutzers und den Zugriffsschlüssel.

Der Zugriffsschlüssel zur Verwendung in X-Auth-Token wird bei erfolgreicher Anmeldung des Nutzers übergeben (s. Nutzer anmelden).


Vorlage: Authentifizierte GET Anfrage HTTP GET JSON Mit Authentifizierung
GET /api/v2/sichtbeobachtungen HTTP/1.1
Host: artenfinder.hessen.de 
X-Auth-User: jdoe
X-Auth-Token: pndVpURTRaREkz

Eine authentifizierte Anfrage mittels cURL

Beispiel: Authentifizierte GET Anfrage über Kommandozeile mittels cURL cURL HTTP GET JSON Mit Authentifizierung
curl -H "X-Auth-User: jdoe" -H "X-Auth-Token: pndVpURTRaREkz" -X GET http://artenfinder.hessen.de/api/v2/sichtbeobachtungen

Eine authentifizierte Anfrage in JavaScript

Beispiel: Authentifizierte GET Anfrage in JavaScript / jQuery jQuery HTTP GET JavaScript (JSONP) Mit Authentifizierung
jQuery.ajax({type: 'GET', url: 'http://artenfinder.hessen.de/api/v2/sichtbeobachtungen',
beforeSend: function(xhr, settings) { 
   xhr.setRequestHeader('X-Auth-User', 'jdoe');
   xhr.setRequestHeader('X-Auth-Token', 'pndVpURTRaREkz'); 
}, dataType: 'jsonp', success: function(contents) { … }}); 

Eine authentifizierte Anfrage in Python

Beispiel: Authentifizierte GET Anfrage in Python Python HTTP GET JSON Mit Authentifizierung
import urllib2
request = urllib2.Request("http://artenfinder.hessen.de/api/v2/sichtbeobachtungen", headers={"X-Auth-User" : "jdoe", "X-Auth-Token": "pndVpURTRaREkz"})
contents = urllib2.urlopen(request).read()

Eine authentifizierte Anfrage in PHP

Beispiel: Authentifizierte GET Anfrage in PHP PHP HTTP GET JSON Mit Authentifizierung
$contents = file_get_contents( 'http://artenfinder.hessen.de/api/v2/sichtbeobachtungen', false, stream_context_create( array( 'http' => array(
  'method' => 'GET',
  'header' => Array('X-Auth-User: jdoe', 'X-Auth-Token: pndVpURTRaREkz')
))));

Eine authentifizierte Anfrage in ASP.NET

Beispiel: Authentifizierte GET Anfrage in ASP.NET ASP.NET HTTP GET JSON Mit Authentifizierung
System.Net.WebClient request = new System.Net.WebClient();
request.Headers.Add( "X-Auth-User", "jdoe" );
request.Headers.Add( "X-Auth-Token", "pndVpURTRaREkz" );
var contents = request.DownloadString( "http://artenfinder.hessen.de/api/v2/sichtbeobachtungen" );

REST Web-Services


Zum Nutzer


Anmelden

Schnittstelle: http://artenfinder.hessen.de/api/v2/login
Methoden:

Parameter: Antwort (bei erfolgreicher Anmeldung): Antwort (bei falscher Anmeldung): Leere Antwort mit HTTP/1.1 200 OK
Antwort (bei fehlenden Parametern): Hinweisende Antwort mit HTTP/1.1 400 Bad Request


Beispiel: Erfolgreiche Login-Anfrage HTTP GET JSON
http://artenfinder.hessen.de/api/v2/login?loginname=mustermann&password=d68d278ebf67570386e222f79a65bd1a5979f61bf
Antwort
{"name":"Hans Mustermann","id":3,"token":"pndVpURTRaREkz","loginname":"mustermann"}

Beispiel: Erfolgreiche Login-Anfrage beantwortet in XML HTTP GET XML
http://artenfinder.hessen.de/api/v2/login?format=xml&loginname=mustermann&password=d68d278ebf67570386e222f79a65bd1a5979f61bf
Antwort
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<result><name>Hans Mustermann</name><id>3</id><token>pndVpURTRaREkz</token><loginname>mustermann</loginname></result>

Beispiel: Login-Anfrage in JavaScript / jQuery jQuery HTTP GET JavaScript (JSONP)
jQuery.ajax({ statusCode : { 200 : function( data ) { if( data && data.id ) { /* ... Login OK ... */ } else { /* ... Login fehlerhaft ... */ }}}, type: 'GET', url: 'http://artenfinder.hessen.de/api/v2/login?', data : { loginname: 'mustermann', password: 'd68d278ebf67570386e222f79a65bd1a5979f61bf' }, dataType : 'jsonp', error : function( xmlhttp ){ /* ... Verbindung fehlerhaft ... */ }});

Zur geforderten Kodierung eines Passwortes in SHA-1 mittels JavaScript bieten sich die "JavaScript implementations of standard and secure cryptographic algorithms" an. (Linkverweis: https://code.google.com/p/crypto-js/#SHA-1)


Registrieren/Anlegen

Schnittstelle: http://artenfinder.hessen.de/api/v2/register

Hinweise zur Registrierung

Nach erfolgreicher Anfrage zur Registrierung wird eine E-Mail entsprechend der vorhandenen Drupal 7 Registrierungsrichtlinie an die angegebene E-Mail Adresse versand.

Methoden: Parameter: Antwort (bei erfolgreicher Registrierungsanfrage): Antwort (bei fehlenden oder fehlerhaften Parametern): Hinweisende Antwort mit HTTP/1.1 400 Bad Request


Beispiel: Erfolgreiche Registrierungs-Anfrage HTTP GET JSON
http://artenfinder.hessen.de/api/v2/register?loginname=mustermann&email=hans.mustermann@xyz.de&vorname=Hansn&nachname=Mustermann
Antwort
{"login":"mustermann","name":"Hans Mustermann","email":"hans.mustermann@xyz.de"}

Ändern der Nutzerinformationen

Schnittstelle: http://artenfinder.hessen.de/api/v2/nutzer/:id

Rechteverwaltung

Die Berechtigung zur Bearbeitung erhält der Besitzer des Nutzerkontos sowie authentisierte Nutzer der Rolle Administrator.

Einige Änderungen von Nutzerinformationen (Vor-, Nachname und Rollenzuordnungen) sind allein Nutzern der Rolle Administrator vorbehalten.

Methoden: Header (für Authentifizierung): optionale Datenfelder: optionale Parameter: Antwort (bei erfolgreicher Bearbeitung): HTTP/1.1 200 OK
Antwort (bei zwar authentisierter jedoch unberechtigter Anfrage): HTTP/1.1 403 Forbidden


Vorlage: Authentifizierte PUT Anfrage HTTP PUT Mit Authentifizierung
PUT /api/v2/nutzer/325627 HTTP/1.1
Host: artenfinder.hessen.de 
X-Auth-User: jdoe
X-Auth-Token: pndVpURTRaREkz
Content-Type: multipart/form-data; charset=utf-8; boundary=--------------------31063722920652
------------------------------31063722920652
Content-Disposition: form-data; name="email"

jdoe2014@provider.de
-----------------------------31063722920652--

Einige Umgebungen unterstützen u.U. die REST Methode PUT nicht, oder die Umsetzung ist schwierig. Hierfür erlaubt der Webservice Methoden im Header zu überladen. Verwenden Sie in einem solchen Fall POST und übergeben im Header in X-HTTP-Method-Override die gewünschte Methode PUT.

Vorlage: Authentifizierte PUT Anfrage über POST senden HTTP PUT (OVERRIDING POST) Mit Authentifizierung
POST /api/v2/sichtbeobachtungen/34435 HTTP/1.1
Host: artenfinder.hessen.de 
X-HTTP-Method-Override: PUT
X-Auth-User: jdoe
X-Auth-Token: pndVpURTRaREkz
Content-Type: multipart/form-data; charset=utf-8; boundary=--------------------31063722920652
------------------------------31063722920652
Content-Disposition: form-data; name="email"

jdoe2014@provider.de
-----------------------------31063722920652--

Eine authentifizierte Bearbeitung eines Nutzerkontos mittels cURL
Beispiel: Authentifizierte Bearbeitung eines Nutzerkontos in der Kommandozeile mittels cURL cURL HTTP PUT Mit Authentifizierung
curl -i -H "X-Auth-User: jdoe" -H "X-Auth-Token: pndVpURTRaREkz" -H "Content-Type: multipart/form-data; charset=utf-8" -F "email=jdoe2014@provider.de" -X PUT http://artenfinder.hessen.de/api/v2/nutzer/124561
Eine authentifizierte Bearbeitung eines Nutzerkontos in PHP
Beispiel: Authentifizierte PUT Bearbeitung eines Nutzerkontos in PHP PHP HTTP PUT Mit Authentifizierung
define('MULTIPART_BOUNDARY', '--------------------------'.microtime(true));
$contents = file_get_contents( 'http://artenfinder.hessen.de/api/v2/nutzer/34435', false, stream_context_create( array( 'http' => array(
  'method' => 'PUT',
  'header' => Array('X-Auth-User: jdoe', 'X-Auth-Token: pndVpURTRaREkz', 'Content-Type: multipart/form-data; charset=utf-8; boundary='.MULTIPART_BOUNDARY),
  'content' =>
    '--'.MULTIPART_BOUNDARY."\r\n".'Content-Disposition: form-data; name="email"'."\r\n\r\n".
    'jdoe2014@provider.de'."\r\n".
    '--'.MULTIPART_BOUNDARY.'--'."\r\n"   
))));

Eine authentifizierte Bearbeitung eines Nutzerkontos in JavaScript
Beispiel: Authentifizierte PUT Bearbeitung eines Nutzerkontos in JavaScript / jQuery JavaScript HTTP PUT (OVERRIDING POST) Mit Authentifizierung
var data = new FormData();
data.append( 'email', 'jdoe2014@provider.de' );

jQuery.ajax({type: 'POST', crossDomain: true, url: 'http://artenfinder.hessen.de/api/v2/nutzer/34435', cache: false, contentType: false, processData: false, data: data,
beforeSend: function(xhr, settings) { 
  xhr.setRequestHeader('X-HTTP-Method-Override', 'PUT');
  xhr.setRequestHeader('X-Auth-User', 'jdoe');
  xhr.setRequestHeader('X-Auth-Token', 'pndVpURTRaREkz'); 
}, dataType: 'json', success: function(contents) { … }}); 

Löschen von Nutzerinformationen

Schnittstellendefinition unter Zum Nutzer > Ändern der Nutzerinformationen.

Rechteverwaltung

Die Berechtigung zum Löschen von Benutzerinformationen erhält der Besitzer des Nutzerkontos sowie authentisierte Nutzer der Rolle Administrator.

Einige Löschungen von Nutzerinformationen (Vor-, Nachname und Rollenzuordnungen) sind allein Nutzern der Rolle Administrator vorbehalten.

Hinweise zum Löschen von Nutzerinformationen

Zum Löschen von Benutzerinformationen das entsprechende Datenfeld analog zu „Ändern der Nutzerinformationen” mit leerem Inhalt übertragen.


Abfragen (Details eines Nutzerkontos, inklusive Berechtigungen)

Schnittstelle: http://artenfinder.hessen.de/api/v2/nutzer/:id

Rechteverwaltung

Neben der Erlaubnis das eigene Nutzerkonto abzurufen erhalten ausschliesslich authentisierte Nutzer der Rolle Administrator Einsicht in fremde Nutzerprofile.

Methoden: Header (für Authentifizierung): optionale Parameter Antwort:


Nach Nutzern suchen

Schnittstelle: http://artenfinder.hessen.de/api/v2/nutzer

Rechteverwaltung

Die Suchantwort unterliegt der Rechteverwaltung. Ausschliesslich authentisierte Nutzer der Rolle Administrator erhalten Einsicht in fremde Nutzerprofile.

Methoden: Header (für Authentifizierung): Parameter: Antwort:


Zu Arten


Abfragen (der Artengruppenliste)

Schnittstelle: http://artenfinder.hessen.de/api/v2/artengruppen
Methoden:

Parameter: Antwort:
Beispiel: Abfrage aller Artengruppen HTTP GET JSON
http://artenfinder.hessen.de/api/v2/artengruppen Link
Antwort
{"result":[{"id":349200,"name_deutsch":"Zikaden","is_animal":true},…]}

Beispiel: Abfrage aller Artengruppen beantwortet in XML HTTP GET XML
http://artenfinder.hessen.de/api/v2/artengruppen?format=xml Link
Antwort
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<xml><result><row><id>347838</id><name_deutsch>Zikaden</name_deutsch><is_animal>TRUE</is_animal></row>…</result></xml>

Abfragen (der Artenliste)

Schnittstelle: http://artenfinder.hessen.de/api/v2/arten
Methoden:

Parameter: Antwort:
Beispiel: Abfrage aller Arten HTTP GET JSON
http://artenfinder.hessen.de/api/v2/arten Link
Antwort
{"result":[{"id":342930,"eu_guid":"urn:lsid:faunaeur.org:taxname:440164","name_wissenschaftlich":"Synanthedon loranthi","name_deutsch":"Mistel-Glasflügler","artengruppe":"Baeren- Spinner","gid":342930,"is_animal":true},…]}

Beispiel: Abfrage aller Arten beantwortet in XML HTTP GET XML
http://artenfinder.hessen.de/api/v2/arten?format=xml Link
Antwort
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<xml><result><row><id>342930</id><eu_guid>urn:lsid:faunaeur.org:taxname:440164</eu_guid><name_wissenschaftlich>Synanthedon loranthi</name_wissenschaftlich><name_deutsch>Mistel-Glasflügler</name_deutsch><artengruppe>Baeren- Spinner</artengruppe><gid>342930</gid><is_animal>TRUE</is_animal></row>…</result></xml>

Abfragen (Artenliste zur Artengruppe)

Schnittstellendefinition unter Zu Arten > Abfragen (der Artenliste).


Beispiel: Liste der Arten zur Artengruppe mit Namen Vögel HTTP GET JSON
http://artenfinder.hessen.de/api/v2/arten?artengruppe=Vögel Link
Antwort
{"result":[{"id":710277,"eu_guid":"urn:lsid:faunaeur.org:taxname:97372","name_wissenschaftlich":"Phylloscopus ibericus","name_deutsch":"Iberienzilpzalp","artengruppe":"V\u00f6gel","gid":346562,"is_animal":true},…]}

Beispiel: Liste der Arten zur Artengruppen-ID 342930 HTTP GET JSON
http://artenfinder.hessen.de/api/v2/arten?gid=342930 Link
Antwort
{"result":[{"id":710234,"eu_guid":"urn:lsid:faunaeur.org:taxname:447022","name_wissenschaftlich":"Chelis maculosa","name_deutsch":"Schwarzgefleckter Bär","artengruppe":"Baeren- Spinner","gid":342930,"is_animal":true},…]}

Beispiel: Liste der Arten zur Artengruppen-ID 342930 mit Rückgabe in XML HTTP GET XML
http://artenfinder.hessen.de/api/v2/arten?gid=342930&format=xml Link
Antwort
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<xml><result><row><id>710234</id><eu_guid>urn:lsid:faunaeur.org:taxname:447022</eu_guid><name_wissenschaftlich>Chelis maculosa</name_wissenschaftlich><name_deutsch>Schwarzgefleckter Bär</name_deutsch><artengruppe>Baeren- Spinner</artengruppe><gid>342930</gid><is_animal>TRUE</is_animal></row>…</result></xml>

Suchen (nach Artengruppen und Arten)

Schnittstellendefinition


Beispiel: Suche nach Arten HTTP GET JavaScript (JSONP) Ohne Authentifizierung
http://artenfinder.hessen.de/api/v2/arten?name_regexp_ci=.*Milan.*&limit=10&callback=myResponseFunc Link
Antwort
myResponseFunc({"result":[{"id":175867,"eu_guid":"urn:lsid:indexfungorum.org:names:232492","name_wissenschaftlich":"Psilocybe semilanceata","name_deutsch":"Spitzkegeliger Kahlkopf","artengruppe":"Pilze","gid":276441,"is_animal":false},…]});

Beispiel: Suche nach Arten HTTP GET JavaScript (JSONP) Ohne Authentifizierung
http://artenfinder.hessen.de/api/v2/arten?name_regexp_ci=.*Milan.*&artengruppe=Vögel&limit=10&callback=myResponseFunc Link
Antwort
myResponseFunc({"result":[{"id":103015,"eu_guid":"urn:lsid:marinespecies.org:taxname:212678","name_wissenschaftlich":"Milvus migrans","name_deutsch":"Schwarzmilan","artengruppe":"Vögel","gid":346562,"is_animal":true},…]});

Beispiel: Suche nach Artengruppen HTTP GET JavaScript (JSONP) Ohne Authentifizierung
http://artenfinder.hessen.de/api/v2/artengruppen?is_animal=false&callback=myResponseFunc Link
Antwort
myResponseFunc({"result":[{"id":276441,"name_deutsch":"Pilze","is_animal":false},…]});

Zu Sichtbeobachtungen


Übermitteln (Erstellen neuer Sichtbeobachtungen, inklusive Foto)

Schnittstelle: http://artenfinder.hessen.de/api/v2/sichtbeobachtungen
Methoden:

Header (für Authentifizierung): Datenfelder: optionale Parameter Antwort (bei erfolgreicher Übermittlung): Hinweisende Antwort auf die erstellte Sichtbeobachtung mit HTTP/1.1 201 Created
Antwort (bei fehlerhaftem Übermittlungsversuch): Hinweisende Antwort mit HTTP/1.1 400 Bad Request


Vorlage: Authentifizierte POST Übermittlung einer Sichtbeobachtung inklusive eines Fotos HTTP POST Mit Authentifizierung
POST /api/v2/sichtbeobachtungen HTTP/1.1
Host: artenfinder.hessen.de 
X-Auth-User: jdoe
X-Auth-Token: pndVpURTRaREkz
Content-Length: 7893278
Content-Type: multipart/form-data; charset=utf-8; boundary=--------------------31063722920652
------------------------------31063722920652
Content-Disposition: form-data; name="art"

710277
------------------------------31063722920652
Content-Disposition: form-data; name="srid"

EPSG:25832
------------------------------31063722920652
Content-Disposition: form-data; name="lon"

446417
------------------------------31063722920652
Content-Disposition: form-data; name="lat"

5542795
------------------------------31063722920652
Content-Disposition: form-data; name="foto"; filename="sb.jpeg"
Content-Type: image/jpeg

AX32qD...
-----------------------------31063722920652--

Eine authentifizierte Übermittlung einer Sichtbeobachtung mittels cURL
Beispiel: Authentifizierte POST Übermittlung einer Sichtbeobachtung inklusive 2 Belegfotos, einem Biotopfoto und Tondatei in der Kommandozeile mittels cURL cURL HTTP POST Mit Authentifizierung
curl -i -H "X-Auth-User: jdoe" -H "X-Auth-Token: pndVpURTRaREkz" -H "Content-Type: multipart/form-data; charset=utf-8" -F "art=710277" -F "lon=446417" -F "lat=5542795" -F "srid=EPSG:25832" -F "foto=@sb.jpeg" -F "foto_2=@sb2.jpeg" -F "biotopfoto=@biotop.jpeg" -F "audio=@aufnahme.mp3" -X POST http://artenfinder.hessen.de/api/v2/sichtbeobachtungen
Eine authentifizierte Übermittlung einer Sichtbeobachtung in PHP
Beispiel: Authentifizierte POST Übermittlung einer Sichtbeobachtung inklusive 2 Belegfotos, einem Biotopfoto und Tondatei in PHP PHP HTTP POST Mit Authentifizierung
define('MULTIPART_BOUNDARY', '--------------------------'.microtime(true));
$contents = file_get_contents( 'http://artenfinder.hessen.de/api/v2/sichtbeobachtungen', false, stream_context_create( array( 'http' => array(
  'method' => 'POST',
  'header' => Array('X-Auth-User: jdoe', 'X-Auth-Token: pndVpURTRaREkz', 'Content-Type: multipart/form-data; charset=utf-8; boundary='.MULTIPART_BOUNDARY),
  'content' =>
    '--'.MULTIPART_BOUNDARY."\r\n".'Content-Disposition: form-data; name="art"'."\r\n\r\n".
    '710277'."\r\n".
    '--'.MULTIPART_BOUNDARY."\r\n".'Content-Disposition: form-data; name="srid"'."\r\n\r\n".
    'EPSG:25832'."\r\n".
    '--'.MULTIPART_BOUNDARY."\r\n".'Content-Disposition: form-data; name="lon"'."\r\n\r\n".
    '446417'."\r\n".
    '--'.MULTIPART_BOUNDARY."\r\n".'Content-Disposition: form-data; name="lat"'."\r\n\r\n".
    '5542795'."\r\n".
    '--'.MULTIPART_BOUNDARY."\r\n".'Content-Disposition: form-data; name="foto"; filename="sb.jpeg"'."\r\n".
    'Content-Type: image/jpeg'."\r\n\r\n".file_get_contents('./sb.jpeg')."\r\n".
    '--'.MULTIPART_BOUNDARY."\r\n".'Content-Disposition: form-data; name="foto_2"; filename="sb2.jpeg"'."\r\n".
    'Content-Type: image/jpeg'."\r\n\r\n".file_get_contents('./sb2.jpeg')."\r\n".
    '--'.MULTIPART_BOUNDARY."\r\n".'Content-Disposition: form-data; name="biotopfoto"; filename="biotop.jpeg"'."\r\n".
    'Content-Type: image/jpeg'."\r\n\r\n".file_get_contents('./biotop.jpeg')."\r\n".
    '--'.MULTIPART_BOUNDARY."\r\n".'Content-Disposition: form-data; name="audio"; filename="aufnahme.mp3"'."\r\n".
    'Content-Type: audio/mpeg'."\r\n\r\n".file_get_contents('./aufnahme.mp3')."\r\n".
    '--'.MULTIPART_BOUNDARY.'--'."\r\n"   
))));

Eine authentifizierte Übermittlung einer Sichtbeobachtung in JavaScript
Beispiel: Authentifizierte POST Übermittlung einer Sichtbeobachtung inklusive 2 Belegfotos, einem Biotopfoto und Tondatei in JavaScript / jQuery JavaScript / jQuery HTTP POST (CORS) Mit Authentifizierung
var data = new FormData();
data.append( 'art', '710277' );
data.append( 'srid', 'EPSG:25832' );
data.append( 'lon', '446417' );
data.append( 'lat', '5542795' );
data.append( 'foto', jQuery('input[type="file"][name="foto"]')[0].files[0] );
data.append( 'foto_2', jQuery('input[type="file"][name="foto_2"]')[0].files[0] );
data.append( 'biotopfoto', jQuery('input[type="file"][name="biotopfoto"]')[0].files[0] );
data.append( 'audio', jQuery('input[type="file"][name="audio"]')[0].files[0] );

jQuery.ajax({type: 'POST', crossDomain: true, url: 'http://artenfinder.hessen.de/api/v2/sichtbeobachtungen', cache: false, contentType: false, processData: false, data: data,
beforeSend: function(xhr, settings) { 
  xhr.setRequestHeader('X-Auth-User', 'jdoe');
  xhr.setRequestHeader('X-Auth-Token', 'pndVpURTRaREkz'); 
}, dataType: 'json', success: function(contents) { … }}); 

Abfragen (Details einer Sichtbeobachtung)

Naturschutzfachlich sensible Arten

Koordinaten für regional naturschutzfachlich sensible Arten oder für als sensibel gekennzeichnete Sichtbeobachtungen werden nicht exakt, sondern als Mittelpunkt eines 5x5km² Rasters ausgegeben. Ausgenommen hiervon sind authentifizierte Nutzer der Rollen Administrator, Experte und Eigentümer der abgerufenen Sichtbeobachtungen.

Schnittstelle: http://artenfinder.hessen.de/api/v2/sichtbeobachtungen/:id
Methoden:

optionaler Header (für Authentifizierung): optionale Parameter Antwort:


Beispiel: Detailanfrage einer Sichtbeobachtung HTTP GET JSON Ohne Authentifizierung
http://artenfinder.hessen.de/api/v2/sichtbeobachtungen/50180093 Link
Antwort
{"result":[{"id":50180093,"bereich":"Öffentliche Meldungen","status":"Freigegeben","anzahl":"1","lon":452768,"lat":5448391,"datum":"01.10.2013","titel_deutsch":"Herbst-Mosaikjungfer","titel_wissenschaftlich":"Aeshna mixta","foto":"http://artenfinder.hessen.de/sites/default/files/afsp/multimedia/foto/sb/2013/10/01/50180093_1.jpg","eu_guid":"urn:lsid:faunaeur.org:taxname:214308","lanis_rlp_osiris_art_id":6833,"phaenogramm":true,"is_animal":true,"artengruppe":"Libellen","lanis_rlp_osiris_artengruppe_id":342431,"mandanten":[{"kuerzel":"RP","name":"Rheinland-Pfalz"}]}]}

Beispiel: Detailanfrage einer Sichtbeobachtung beantwortet in XML HTTP GET XML Ohne Authentifizierung
http://artenfinder.hessen.de/api/v2/sichtbeobachtungen/50180093?format=xml Link
Antwort
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<xml><result><row><id>50180093</id><bereich>Öffentliche Meldungen</bereich><status>Freigegeben</status><anzahl><![CDATA[1]]></anzahl><lon>452768</lon><lat>5448391</lat><datum>01.10.2013</datum><titel_deutsch>Herbst-Mosaikjungfer</titel_deutsch><titel_wissenschaftlich>Aeshna mixta</titel_wissenschaftlich><foto>http://artenfinder.hessen.de/sites/default/files/afsp/multimedia/foto/sb/2013/10/01/50180093_1.jpg</foto><eu_guid>urn:lsid:faunaeur.org:taxname:214308</eu_guid><lanis_rlp_osiris_art_id>6833</lanis_rlp_osiris_art_id><is_animal>TRUE</is_animal><phaenogramm>TRUE</phaenogramm><artengruppe>Libellen</artengruppe><lanis_rlp_osiris_artengruppe_id>342431</lanis_rlp_osiris_artengruppe_id><mandanten><row><kuerzel>RP</kuerzel><name>Rheinland-Pfalz</name></row></mandanten></row></result></xml>

Beispiel: Detailanfrage einer Sichtbeobachtung beantwortet in JavaScript mittels JSONP HTTP GET JavaScript (JSONP) Ohne Authentifizierung
http://artenfinder.hessen.de/api/v2/sichtbeobachtungen/50180093?callback=myResponseFunc Link
Antwort
myResponseFunc({"result":[{"id":50180093,"bereich":"Öffentliche Meldungen","status":"Freigegeben","anzahl":"1","lon":452768,"lat":5448391,"datum":"01.10.2013","titel_deutsch":"Herbst-Mosaikjungfer","titel_wissenschaftlich":"Aeshna mixta","foto":"http://artenfinder.hessen.de/sites/default/files/afsp/multimedia/foto/sb/2013/10/01/50180093_1.jpg","eu_guid":"urn:lsid:faunaeur.org:taxname:214308","lanis_rlp_osiris_art_id":6833,"phaenogramm":true,"is_animal":true,"artengruppe":"Libellen","lanis_rlp_osiris_artengruppe_id":342431,"mandanten":[{"kuerzel":"RP","name":"Rheinland-Pfalz"}]}]});

Bearbeiten (einer Sichtbeobachtung)

Schnittstelle: http://artenfinder.hessen.de/api/v2/sichtbeobachtungen/:id

Rechteverwaltung

Die Berechtigung zur Bearbeitung besitzt der Autor einer Sichtbeobachtung soweit diese nicht durch Experten freigegeben wurde. Hierbei lassen sich Datenfelder nur im privatem Bereich nachbearbeiten (ein Sonderfall stellt bereich dar welches ohne Bereichseinschränkung editiert werden kann).

Hinweise zur Bearbeitung

Zur Entfernung einzelner Fotos, der Tondatei oder der Bemerkung das entsprechende Datenfeld mit leerem Inhalt übertragen.
Die übertragene Bemerkung bemerkung wird entsprechend dem anfragestellendem, authorisierten Nutzer (Autoren- oder Expertenbemerkung) zugeordnet.

Methoden: Header (für Authentifizierung): Datenfelder: optionale Parameter Antwort (bei erfolgreicher Bearbeitung): HTTP/1.1 200 OK
Antwort (bei zwar authentisierter jedoch unberechtigter Anfrage): HTTP/1.1 403 Forbidden


Vorlage: Authentifizierte PUT Anfrage HTTP PUT Mit Authentifizierung
PUT /api/v2/sichtbeobachtungen/325627 HTTP/1.1
Host: artenfinder.hessen.de 
X-Auth-User: jdoe
X-Auth-Token: pndVpURTRaREkz
Content-Type: multipart/form-data; charset=utf-8; boundary=--------------------31063722920652
------------------------------31063722920652
Content-Disposition: form-data; name="bemerkung"

Eine abgeänderte Bemerkung
-----------------------------31063722920652--

Einige Umgebungen unterstützen u.U. die REST Methode PUT nicht, oder die Umsetzung ist schwierig. Hierfür erlaubt der Webservice Methoden im Header zu überladen. Verwenden Sie in einem solchen Fall POST und übergeben im Header in X-HTTP-Method-Override die gewünschte Methode PUT.

Vorlage: Authentifizierte PUT Anfrage über POST senden HTTP PUT (OVERRIDING POST) Mit Authentifizierung
POST /api/v2/sichtbeobachtungen/34435 HTTP/1.1
Host: artenfinder.hessen.de 
X-HTTP-Method-Override: PUT
X-Auth-User: jdoe
X-Auth-Token: pndVpURTRaREkz
Content-Type: multipart/form-data; charset=utf-8; boundary=--------------------31063722920652
------------------------------31063722920652
Content-Disposition: form-data; name="bemerkung"

Eine abgeänderte Bemerkung
-----------------------------31063722920652--

Eine authentifizierte Bearbeitung einer Sichtbeobachtung mittels cURL
Beispiel: Authentifizierte Bearbeitung einer Sichtbeobachtung in der Kommandozeile mittels cURL cURL HTTP PUT Mit Authentifizierung
curl -i -H "X-Auth-User: jdoe" -H "X-Auth-Token: pndVpURTRaREkz" -H "Content-Type: multipart/form-data; charset=utf-8" -F "bemerkung=Eine abgeänderte Bemerkung" -X PUT http://artenfinder.hessen.de/api/v2/sichtbeobachtungen/124561
Eine authentifizierte Bearbeitung einer Sichtbeobachtung in PHP
Beispiel: Authentifizierte PUT Bearbeitung einer Sichtbeobachtung in PHP PHP HTTP PUT Mit Authentifizierung
define('MULTIPART_BOUNDARY', '--------------------------'.microtime(true));
$contents = file_get_contents( 'http://artenfinder.hessen.de/api/v2/sichtbeobachtungen/34435', false, stream_context_create( array( 'http' => array(
  'method' => 'PUT',
  'header' => Array('X-Auth-User: jdoe', 'X-Auth-Token: pndVpURTRaREkz', 'Content-Type: multipart/form-data; charset=utf-8; boundary='.MULTIPART_BOUNDARY),
  'content' =>
    '--'.MULTIPART_BOUNDARY."\r\n".'Content-Disposition: form-data; name="bemerkung"'."\r\n\r\n".
    'Eine abgeänderte Bemerkung'."\r\n".
    '--'.MULTIPART_BOUNDARY.'--'."\r\n"   
))));

Eine authentifizierte Bearbeitung einer Sichtbeobachtung in JavaScript
Beispiel: Authentifizierte PUT Bearbeitung einer Sichtbeobachtung in JavaScript / jQuery JavaScript HTTP PUT (OVERRIDING POST) Mit Authentifizierung
var data = new FormData();
data.append( 'bemerkung', 'Eine abgeänderte Bemerkung' );

jQuery.ajax({type: 'POST', crossDomain: true, url: 'http://artenfinder.hessen.de/api/v2/sichtbeobachtungen/34435', cache: false, contentType: false, processData: false, data: data,
beforeSend: function(xhr, settings) { 
  xhr.setRequestHeader('X-HTTP-Method-Override', 'PUT');
  xhr.setRequestHeader('X-Auth-User', 'jdoe');
  xhr.setRequestHeader('X-Auth-Token', 'pndVpURTRaREkz'); 
}, dataType: 'json', success: function(contents) { … }}); 

Löschen (einer Sichtbeobachtung)

Schnittstelle: http://artenfinder.hessen.de/api/v2/sichtbeobachtungen/:id

Rechteverwaltung

Die Berechtigung zum Löschen einer Sichtbeobachtung ist beschränkt auf den Autor soweit diese nicht durch Experten freigegeben wurde. Zusätzlich sind Nutzer der Rolle Administrator berechtigt jedwede veröffentlichte Sichtbeobachtung zu löschen.

Methoden: Header (für Authentifizierung): optionale Parameter Antwort (bei erfolgreicher Löschung): HTTP/1.1 200 OK
Antwort (bei zwar authentisierter jedoch unberechtigter Anfrage): HTTP/1.1 403 Forbidden


Vorlage: Authentifizierte DELETE Anfrage HTTP DELETE Mit Authentifizierung
DELETE /api/v2/sichtbeobachtungen/325627 HTTP/1.1
Host: artenfinder.hessen.de 
X-Auth-User: jdoe
X-Auth-Token: pndVpURTRaREkz

Einige Umgebungen unterstützen u.U. die REST Methode DELETE nicht, oder die Umsetzung ist schwierig. Hierfür erlaubt der Webservice Methoden im Header zu überladen. Verwenden Sie in einem solchen Fall POST und übergeben im Header in X-HTTP-Method-Override die gewünschte Methode DELETE.

Vorlage: Authentifizierte DELETE Anfrage über POST senden HTTP DELETE (OVERRIDING POST) Mit Authentifizierung
POST /api/v2/sichtbeobachtungen/34435 HTTP/1.1
Host: artenfinder.hessen.de 
X-HTTP-Method-Override: DELETE
X-Auth-User: jdoe
X-Auth-Token: pndVpURTRaREkz

Eine authentifizierte Löschung einer Sichtbeobachtung mittels cURL
Beispiel: Authentifizierte Löschung einer Sichtbeobachtung in der Kommandozeile mittels cURL cURL HTTP DELETE Mit Authentifizierung
curl -i -H "X-Auth-User: jdoe" -H "X-Auth-Token: pndVpURTRaREkz" -X DELETE http://artenfinder.hessen.de/api/v2/sichtbeobachtungen/124561

Abfragen (der Liste der Sichtbeobachtungen)

Schnittstelle: http://artenfinder.hessen.de/api/v2/sichtbeobachtungen

Rechteverwaltung

Für nicht authentisierte Anfragen ist die Auflistung der Sichtbeobachtungen gefiltert auf veröffentlichte und durch Experten freigegebene Sichtbeobachtungen.

Authensierte Nutzer erhalten eine erweiterte Auflistung aller veröffentlichten Sichtbeobachtungen, uneingeschränkt des jeweiligen Meldestatus. Zusätzlich ist Ihnen die Auflistung des eigenen privaten Bereiches gegeben.
Eine weitere Differenzierung ist in der Antwort einzelner Beobachtungen abgebildet: Detailinformationen wie z.B. Erfasser erfasser sind allein authentisierten Anfragestellern ersichtlich.

Naturschutzfachlich sensible Arten

Koordinaten für regional naturschutzfachlich sensible Arten werden nicht exakt, sondern als Mittelpunkt eines 5x5km² Rasters ausgegeben. Ausgenommen hiervon sind authentifizierte Nutzer der Rollen Administrator, Experte und Eigentümer der abgerufenen Sichtbeobachtungen.

Methoden: optionaler Header (für Authentifizierung): Parameter: Antwort:


Beispiel: Abfrage von Sichtbeobachtungen HTTP GET JSON Ohne Authentifizierung
http://artenfinder.hessen.de/api/v2/sichtbeobachtungen Link
Antwort
{"result":[{"id":50180093,"bereich":"Öffentliche Meldungen","status":"Freigegeben","anzahl":"1","lon":452768,"lat":5448391,"datum":"01.10.2013","titel_deutsch":"Herbst-Mosaikjungfer","titel_wissenschaftlich":"Aeshna mixta","foto":"http://artenfinder.hessen.de/afsp/multimedia/foto/sb/2013/10/01/50180093_1.jpg"},…],"next":"http://artenfinder.hessen.de/api/v2/sichtbeobachtungen?format=json&cursor=50180203"}

Beispiel: Abfrage von Sichtbeobachtungen beantwortet in XML HTTP GET XML Ohne Authentifizierung
http://artenfinder.hessen.de/api/v2/sichtbeobachtungen?format=xml Link
Antwort
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<xml><result><row><id>50180093</id><bereich>Öffentliche Meldungen</bereich><status>Freigegeben</status><anzahl><![CDATA[1]]></anzahl><lon>452768</lon><lat>5448391</lat><datum>01.10.2013</datum><titel_deutsch>Herbst-Mosaikjungfer</titel_deutsch><titel_wissenschaftlich>Aeshna mixta</titel_wissenschaftlich><foto>http://artenfinder.hessen.de/afsp/multimedia/foto/sb/2013/10/01/50180093_1.jpg</foto></row>…</result><next><![CDATA[http://artenfinder.hessen.de/api/v2/sichtbeobachtungen?format=xml&cursor=50180203]]></next></xml>

Suchen (nach Sichtbeobachtungen)

Schnittstellendefinition unter Sichtbeobachtungen > Abfragen (der Liste der Sichtbeobachtungen).


Beispiel: Suche nach Sichtbeobachtungen HTTP GET JavaScript (JSONP) Ohne Authentifizierung
http://artenfinder.hessen.de/api/v2/sichtbeobachtungen?titel_wissenschaftlich=milvus milvus&jahr=2011&bbox=405188,5474383,415905,5480017&restrict=id,lat,lon,anzahl&callback=myResponseFunc Link
Antwort
myResponseFunc({"result":[{"id":37062223,"lon":412612,"lat":5479349,"anzahl":"1"},…],"next":"http://artenfinder.hessen.de/api/v2/sichtbeobachtungen?cursor=37226794&titel_wissenschaftlich=milvus milvus&jahr=2011&bbox=405188,5474383,415905,5480017&restrict=id,lat,lon,anzahl"});

Veröffentlichen (einer eigenen Sichtbeobachtung)

Schnittstelle: http://artenfinder.hessen.de/api/v2/sichtbeobachtungen/:id

Rechteverwaltung

Die Berechtigung zur Veröffentlichung ist beschränkt auf den Autor einer Sichtbeobachtung.

Methoden: Header (für Authentifizierung): Datenfelder optionale Parameter Antwort (bei erfolgreicher Bearbeitung): HTTP/1.1 200 OK
Antwort (bei zwar authentisierter jedoch unberechtigter Anfrage): HTTP/1.1 403 Forbidden


Vorlage: Authentifizierte PUT Anfrage HTTP PUT Mit Authentifizierung
PUT /api/v2/sichtbeobachtungen/325627 HTTP/1.1
Host: artenfinder.hessen.de 
X-Auth-User: jdoe
X-Auth-Token: pndVpURTRaREkz
Content-Type: multipart/form-data; charset=utf-8; boundary=--------------------31063722920652
------------------------------31063722920652
Content-Disposition: form-data; name="bereich"

oeffentlich
-----------------------------31063722920652--

Einige Umgebungen unterstützen u.U. die REST Methode PUT nicht, oder die Umsetzung ist schwierig. Hierfür erlaubt der Webservice Methoden im Header zu überladen. Verwenden Sie in einem solchen Fall POST und übergeben im Header in X-HTTP-Method-Override die gewünschte Methode PUT.

Vorlage: Authentifizierte PUT Anfrage über POST senden HTTP PUT (OVERRIDING POST) Mit Authentifizierung
POST /api/v2/sichtbeobachtungen/34435 HTTP/1.1
Host: artenfinder.hessen.de 
X-HTTP-Method-Override: PUT
X-Auth-User: jdoe
X-Auth-Token: pndVpURTRaREkz
Content-Type: multipart/form-data; charset=utf-8; boundary=--------------------31063722920652
------------------------------31063722920652
Content-Disposition: form-data; name="bereich"

oeffentlich
-----------------------------31063722920652--

Eine authentifizierte Veröffentlichung einer Sichtbeobachtung mittels cURL
Beispiel: Authentifizierte Veröffentlichung einer Sichtbeobachtung in der Kommandozeile mittels cURL cURL HTTP PUT Mit Authentifizierung
curl -i -H "X-Auth-User: jdoe" -H "X-Auth-Token: pndVpURTRaREkz" -H "Content-Type: multipart/form-data; charset=utf-8" -F "bereich=oeffentlich" -X PUT http://artenfinder.hessen.de/api/v2/sichtbeobachtungen/124561
Eine authentifizierte Veröffentlichung einer Sichtbeobachtung in PHP
Beispiel: Authentifizierte Veröffentlichung einer Sichtbeobachtung in PHP PHP HTTP PUT Mit Authentifizierung
define('MULTIPART_BOUNDARY', '--------------------------'.microtime(true));
$contents = file_get_contents( 'http://artenfinder.hessen.de/api/v2/sichtbeobachtungen/34435', false, stream_context_create( array( 'http' => array(
  'method' => 'PUT',
  'header' => Array('X-Auth-User: jdoe', 'X-Auth-Token: pndVpURTRaREkz', 'Content-Type: multipart/form-data; charset=utf-8; boundary='.MULTIPART_BOUNDARY),
  'content' =>
    '--'.MULTIPART_BOUNDARY."\r\n".'Content-Disposition: form-data; name="bereich"'."\r\n\r\n".
    'oeffentlich'."\r\n".
    '--'.MULTIPART_BOUNDARY.'--'."\r\n"   
))));

Eine authentifizierte Veröffentlichung einer Sichtbeobachtung in JavaScript
Beispiel: Authentifizierte Veröffentlichung einer Sichtbeobachtung in JavaScript / jQuery JavaScript HTTP PUT (OVERRIDING POST) Mit Authentifizierung
var data = new FormData();
data.append( 'bereich', 'oeffentlich' );

jQuery.ajax({type: 'POST', crossDomain: true, url: 'http://artenfinder.hessen.de/api/v2/sichtbeobachtungen/34435', cache: false, contentType: false, processData: false, data: data,
beforeSend: function(xhr, settings) { 
  xhr.setRequestHeader('X-HTTP-Method-Override', 'PUT');
  xhr.setRequestHeader('X-Auth-User', 'jdoe');
  xhr.setRequestHeader('X-Auth-Token', 'pndVpURTRaREkz'); 
}, dataType: 'json', success: function(contents) { … }}); 

Erweitert


Abfragen nach täglichen/stündlichen Änderungen von Sichtbeobachtungen (CREATE/UPDATE/DELETE) für inkrementellen Datenabgleich

Schnittstelle: http://artenfinder.hessen.de/api/v2/protokoll

Hinweise zum Datenabgleich

Änderungen von Sichtbeobachtungen werden in einer sequentiellen Liste abgelegt. Die Liste ist im LCFS-Prinzip („Last Come, First Served“) implementiert und protokolliert Schreiboperationen der hinterlegten Sichtbeobachtungen (CREATE/UPDATE/DELETE).

Methoden: Parameter: Antwort:


Abfragen auf das Protokoll der Qualitätssicherung (Abgelehnt, Freigegeben, mit Hinweis versehen, In Prüfung)

Schnittstelle: http://artenfinder.hessen.de/api/v2/qs

Rechteverwaltung

Abfragen auf das Protokoll der Qualitätssicherung sind allein authentisierten Nutzern der Rolle Experte oder Administrator vorbehalten.

Hinweise zum Protokoll

Das Protokoll der Qualitätssicherung wird in einer sequentiellen Liste abgelegt. Die Liste ist im LCFS-Prinzip („Last Come, First Served“) implementiert.

Methoden: Header (für Authentifizierung): Parameter: Antwort:


Änderungsprotokolle der Web Service API


Änderungsprotokoll vom 03.02.2014, Version 2.0.6
Änderungsprotokoll vom 06.02.2014, Version 2.0.7
Änderungsprotokoll vom 07.02.2014, Version 2.0.8
Änderungsprotokoll vom 24.04.2014, Version 2.0.9
Änderungsprotokoll vom 29.04.2014, Version 2.0.10
Änderungsprotokoll vom 05.06.2014, Version 2.0.11
Änderungsprotokoll vom 18.08.2014, Version 2.0.12
Änderungsprotokoll vom 22.09.2014, Version 2.0.13
Änderungsprotokoll vom 22.09.2014, Version 2.0.14
Änderungsprotokoll vom 01.10.2014, Version 2.0.15
Änderungsprotokoll vom 20.02.2015, Version 2.0.16
Änderungsprotokoll vom 07.12.2016, Version 2.0.17
Änderungsprotokoll vom 23.05.2017, Version 2.0.18
Änderungsprotokoll vom 01.06.2017, Version 2.0.19
Änderungsprotokoll vom 24.08.2017, Version 2.0.20
Änderungsprotokoll vom 20.11.2018, Version 2.0.21
Änderungsprotokoll vom 26.11.2018, Version 2.0.22
Änderungsprotokoll vom 16.08.2019, Version 2.0.23
Änderungsprotokoll vom 23.08.2019, Version 2.0.24
Änderungsprotokoll vom 28.02.2020, Version 2.0.25
Änderungsprotokoll vom 28.02.2020, Version 2.0.26
Änderungsprotokoll vom 02.07.2020, Version 2.0.27
Änderungsprotokoll vom 02.07.2020, Version 2.0.28
Änderungsprotokoll vom 03.08.2020, Version 2.0.29
Änderungsprotokoll vom 19.09.2020, Version 2.0.30
Änderungsprotokoll vom 23.02.2021, Version 2.0.31
Änderungsprotokoll vom 26.03.2021, Version 2.0.32
Änderungsprotokoll vom 26.03.2021, Version 2.0.33
Änderungsprotokoll vom 09.04.2021, Version 2.0.34
Änderungsprotokoll vom 27.07.2021, Version 2.0.35
Änderungsprotokoll vom 02.08.2021, Version 2.0.36
Änderungsprotokoll vom 10.03.2023, Version 2.0.37

FAQ


Keine Einträge vorhanden.


Impressum


Anbieter

Landesamt für Umwelt, Wasserwirtschaft und Gewerbeaufsicht Rheinland-Pfalz
Informations- und Kommunikationstechnik
Kaiser-Friedrich-Straße 7
55116 Mainz
Telefon: 06131 60330
Mail: poststelle(at)luwg.rlp.de


Technische und fachliche Umsetzung

u-werk, Umweltinformationsdienste
www.u-werk.net, info(at)u-werk.net