Laktonaut
Hallo Gast! [anmelden] Lebensmittelsuche | Lebensmittel eintragen | Neueste Einträge

API-Dokumentation

Laktonaut stellt eine Programmierschnittstelle (API) zur Verfügung, über die fremde Anwendungen Informationen aus der Lebensmitteldatenbank beziehen können.

Derzeit ist nur die Abfrage von Informationen zu einem Artikel mit einer gegebenen GTIN (auch EAN oder "Barcode-Nummer" genannt) möglich.

Die Nutzung der API unterliegt unseren Nutzungsbedingungen (siehe dort insbesondere § 8). Sie bedarf unserer schriftlichen Einwilligung.

Eine gewisse Anzahl von Anfragen zu Testzwecken kann grundsätzlich jeder mit Hilfe des test-Schlüssels (siehe unten) durchführen. Nutzer, die in größerem Umfang auf die API zugreifen möchten, werden gebeten, mit uns Kontakt aufzunehmen und uns ihr Anliegen mitzuteilen. Sie erhalten dann gegebenenfalls einen persönlichen Schlüssel zugeteilt, der eine ausreichende Zahl von Anfragen ermöglicht.

Die folgende Dokumentation richtet sich direkt an Anwendungsentwickler. Vorausgesetzt wird ein prinzipielles Verständnis von HTTP-Anfragen und XML-Daten.

Kapitel


Anfrage des Clients

Um eine Anfrage an den Server zu richten, sendet der Client einen HTTP-GET-Request an www.laktonaut.de auf Port 80 für folgende URL:

http://www.laktonaut.de/api.php?action=query&gtin=gtin&key=key

Beispiel: http://www.laktonaut.de/api.php?action=query&gtin=4000417025005&key=test

Parameter

gtin

GTIN (EAN) des gesuchten Artikels

Eine gültige GTIN ist ein String aus zumeist 8 oder 13, manchmal auch 12 oder 14 Ziffern. Formal akzeptiert werden allerdings Strings beliebiger Länge. Alle nichtnumerischen Zeichen (beispielsweise Trennzeichen) werden dabei ignoriert. Führende Nullen sind jedoch von Bedeutung – eine GTIN ist ein String und keine Zahl, 0000012345670 also etwas anderes als 12345670.

Die Angabe wird unabhängig von ihrer Länge als vollständige GTIN interpretiert. Eine Suche nach Teil-GTINs ist derzeit nicht möglich.

key

Persönlicher Zugangsschlüssel des Clients; wird auf Anfrage zugeteilt

Zu Testzwecken kann der Schlüssel test verwendet werden. Dieser ist jedoch einer Begrenzung unterworfen, was die Zahl der Anfragen pro IP und Zeiteinheit angeht.

↑ Seitenanfang


Antwort des Servers

Die Antwort des Servers ist vom Client zunächst auf ihren HTTP-Status-Code hin zu prüfen. Der Server verwendet diese Codes semantisch korrekt gemäß RFC 2616.

Bei einem HTTP-Status-Code von 200 (OK) enthält der Body der Antwort ein XML-Dokument (Content-Type: application/xml) nach folgendem Schema:

<?xml version="1.0" encoding="UTF-8"?>
<laktonaut>
    ...
</laktonaut>

Der Zeichensatz für alle Strings ist UTF-8. Die folgenden fünf Zeichen werden, wie in XML üblich, als Entities kodiert:

Zeichen Entity
" &quot;
& &amp;
' &apos;
< &lt;
> &gt;

Bei zukünftigen Änderungen und Erweiterungen der API wird volle Abwärtskompatibilität angestrebt, so dass auch Clients, die die Aktualisierungen noch nicht kennen, weiterhin funktionieren. Dies setzt eine gewisse Flexibilität des Clients voraus; er sollte seinerseits folgende Punkte beachten:

  • Die Anordnung von Elementen kann sich ändern, ohne dass dies die Semantik beeinflusst. Es gibt keine starre Reihenfolge.
  • Es können neue Elemente hinzukommen. Unbekannte Elemente sind daher nicht als Fehler zu werten, sondern zu ignorieren.
  • Elemente können Attribute erhalten. Beispielsweise könnte aus <item> plötzlich <item info="blabla"> werden. Der Client sollte sie trotzdem erkennen.
  • Leerzeichen, Tabulatoren usw. sind außerhalb von Texten völlig bedeutungslos und können variieren.

Subelemente von <laktonaut>

status
message
item

Die Subelemente status und message kommen jeweils genau einmal vor. Das Subelement item kann beliebig oft vorkommen, je nach Anzahl der gefundenen Artikel. Die Reihenfolge der Subelemente kann variieren.

status

Statuscode der Antwort als numerischer String (signed integer)

Wert Bedeutung
>= 0 Anzahl der gefundenen Artikel
-1 Fehler: formal ungültige Anfrage – Admin: Parameter überprüfen!
-2 Fehler: ungültiger Schlüssel
-3 Fehler: Antwort verweigert
< -3 sonstiger oder unbekannter Fehler – Admin: message beachten!

Werte > 1 sind selten und kommen nur in dem Fall vor, dass eine GTIN mehreren unterschiedlichen Artikeln zugeordnet ist.

Der Wert -3 (Fehler: Antwort verweigert) ist meist Folge einer Überschreitung des Abfragelimits, was vor allem unter Verwendung des test-Schlüssels passieren kann.

Falls eine ungültige oder nicht vergebene GTIN übergeben wurde, wird kein Fehlercode zurückgegeben, sondern schlicht 0.

Beispiel: <status>1</status>

message

Vom Menschen lesbare Mitteilung des Servers

Das Element enthält eine Erfolgs- bzw. Fehlermeldung, die rein informativen Zwecken (z. B. für die Fehlersuche) dient und keinesfalls zur automatischen Statusprüfung verwendet werden sollte, da sie variieren kann.

Beispiel: <message>OK: 1 item found</message>

item

Enthält die Daten zu den gefundenen Artikeln

Pro gefundenem Artikel wird genau ein item-Element geliefert, das diesen Artikel beschreibt. Die Anzahl der item-Elemente entspricht also dem Wert der Angabe aus dem status-Element, sofern dieser >= 0 ist. Im Fehlerfall (status < 0) werden keine item-Elemente geliefert.

Subelemente von <item>

id
gtin
name
generic
category
lactose
link
shortlink
timestamp

Alle Subelemente von item kommen in jedem item-Element jeweils genau einmal vor – mit Ausnahme des Subelements category, das mindestens einmal vorkommt. Die Reihenfolge der Subelemente kann variieren.

id

Laktonaut-interne ID des Artikels als numerischer String (unsigned integer)

Beispiel: <id>3928</id>

gtin

GTIN (EAN) des Artikels als String

Die GTIN besteht in der Regel aus 8, 12, 13 oder 14 Ziffern ohne Trennzeichen. Der String ist nicht numerisch zu interpretieren – führende Nullen sind beizubehalten.

Beispiel: <gtin>4000417025005</gtin>

name

Name des Artikels

Beispiel: <name>Ritter Sport Marzipan 100 g</name>

generic

Generische Bezeichnung (Gattungsname) des Artikels

Beispiel: <generic>Schokolade</generic>

category

Name der Kategorie des Artikels

Das category-Element kann auch mehrfach vorkommen, wenn der Artikel in mehrere Kategorien eingeordnet ist.

Beispiel: <category>Süßigkeiten</category>

lactose

Laktosegehalt des Artikels als String

Wert Bedeutung
yes Der Artikel enthält Laktose (ist laktosehaltig)
no Der Artikel enthält keine Laktose (ist laktosefrei)
anderer Wert unbekannt

Andere Werte als yes oder no (in genau diesen Schreibweisen) sollten in der aktuellen Version der API nicht vorkommen; falls doch, ist die Angabe als unbekannt zu interpretieren. Keinesfalls sollte etwa jeder Wert != yes als laktosefrei interpretiert werden! Aufgrund der zentralen Bedeutung der Angabe zum Laktosegehalt ist hier ganz besondere Sorgfalt angebracht.

Beispiel: <lactose>no</lactose>

link

Link zur Laktonaut-Beschreibungsseite des Artikels als vollständige URL

Dieser Link ist als Verweis zur Quelle zu verwenden.

Beispiel: <link>http://www.laktonaut.de/laktosefrei-ritter-sport-marzipan-100-g-3928.html</link>

Hinweis: Der Link ist auch dann noch gültig, wenn sich die im Dateinamen enthalten Informationen über Laktosegehalt und Produktnamen inzwischen geändert haben sollten. Wichtig ist allein die ID. Es wird jedoch darum gebeten, die URL nicht zu verändern und nur im Notfall den Kurzlink zu verwenden:

shortlink

Kurzlink zur Laktonaut-Beschreibungsseite des Artikels als vollständige URL

Dieser Kurzlink sollte nur dann als Verweis zur Quelle verwendet werden, wenn Platzgründe dazu zwingen. Der im link-Element angegebene vollständige Link ist wann immer möglich zu bevorzugen.

Beispiel: <link>http://www.laktonaut.de/x3928</link>

timestamp

Zeitpunkt der letzten Änderung des Eintrags als Unix-Timestamp (numerischer String, unsigned integer)

Beispiel: <timestamp>1315990392</timestamp>

↑ Seitenanfang


Beispiel

Anfrage

http://www.laktonaut.de/api.php?action=query&gtin=4000417025005&key=test

Antwort

<?xml version="1.0" encoding="UTF-8"?>
<laktonaut>
    <status>1</status>
    <message>OK: 1 item found</message>
    <item>
        <id>3928</id>
        <gtin>4000417025005</gtin>
        <name>Ritter Sport Marzipan 100 g</name>
        <generic>Schokolade</generic>
        <category>Süßigkeiten</category>
        <lactose>no</lactose>
        <link>http://www.laktonaut.de/laktosefrei-ritter-sport-marzipan-100-g-3928.html</link>
        <shortlink>http://www.laktonaut.de/x3928</shortlink>
        <timestamp>1315990392</timestamp>
    </item>
</laktonaut>

↑ Seitenanfang


Bilder

Mit der Zuweisung eines eigenen Schlüssels erhält der API-Nutzer die Erlaubnis, die folgenden Bilder im Kontext der API-Nutzung zu verwenden. Eine unerlaubte Verwendung ist untersagt.

laktonaut_api_logo.png Laktonaut-Logo (PNG, 800 x 200, 12 kB)
laktonaut_api_kuh.png Laktonaut-Kuh (PNG, transparent, 333 x 250, 52 kB)
laktonaut_api_gruen.png Symbol "laktosefrei" (PNG, transparent, 30 x 30, 3 kB)
laktonaut_api_rot.png Symbol "laktosehaltig" (PNG, transparent, 30 x 30, 3 kB)

Wir bitten berechtigte Nutzer darum, die Bilder herunterzuladen und gegebenenfalls in der Größe anzupassen. Eine Direktverlinkung ist nicht erwünscht.

↑ Seitenanfang


Lesezeichen/Favoriten RSS-Feed Facebook Twitter Gesundheitshinweis | Nutzungsbedingungen | Presse | Partner | API | Impressum / Kontakt