OFDB Gateway XML / JSON Schnittstelle

Das OFDBGW ist ein XML/JSON Gateway für die deutsche Online Filmdatenbank, kurz OFDB. Ziel des Gateways ist es eine Anfrage an OFDB absetzen zu können und alle relevanten Information, z.B. ein Suchergebnis oder Filminformation in einer XML bzw. JSON Datei zurückgeliefert zu bekommen um so damit z.B. in einer Applikation wie einer Filmverwaltung weiterarbeiten zu können. Dabei greift das Interface direkt auf den Online Web Service von ofdb.de zu. Die angezeigten Daten werden aus den HTML Webseiten extrahiert.

Das Gateway darf nur für private Zwecke genutzt werden. Eine kommerzielle Nutzung wird generell ausgeschlossen. Außerdem gibt es für das Gateway keinen Support oder irgendwelche Verfügbarkeitszusagen seitens OFDB.de. Sollte es Probleme mit dem Gateway geben, wendet euch bitte an mich.

Agrund von Server Engpässen war das OFDBGW seit dem 11.09.2009 auf Mirror Server ausgelagert. Die in den Beispielen aufgeführte Adresse diente von da an nur noch als eine Art Loadbalancer und verteilte die Anfragen per 302 HTTP Redirect weiter an die Mirror Server.

Leider ist eben diese Seite xml.n4rf.net/ofdbgw/ von Björn Böttcher bereits seit längerem nun gar nicht mehr erreichbar. Aus diesem Grund wurde am 09.02.2010 von Tobias Scheeper das neue Balancer-Gateway ofdbgw.org aufgesetzt. Selbstverständlich kann auch weiterhin direkt auf die entsprechenden Mirror Server zugegriffen werden. Wir bitten jedoch darum, alle Anfragen über den Load-Balancer laufen zu lassen.

Das OFDB-Gateway selbst blieb weitestgehend unverändert. Die aktuell eingesetzte Version ist 1.23

Mirror Priorität Status Powered by
mirror1.ofdbgw.org 1 Scheeper Sales & Service
(Betreiber von ofdbgw.org)
ofdbgw.home-of-root.de 1 Michael Hofmann
ofdbgw.metawave.ch 1 Marcel Ryser
ofdbgw.h1915283.stratoserver.net 1 Eike Kretzmeyer
ofdbgw.johann-scharl.de 1 Johann Scharl
ofdbgw.geeksphere.de 1 Daniel Hatzl

Die Priorität gibt Auskunft darüber wie oft ein Mirror über den Loadbalancer angesprochen wird. Beispiel: Ein Mirror mit Prio 1 würde bei 3 Anfragen in der Regel 2 mal angesprochen, ein Mirror mit Prio 2 nur einmal. Möchte man also einen direkten Mirror nutzen, sollten Mirror mit höherer Prio bevorzugt werden.

Suchen – Modul “search”

Dieses ist sozusagen das Einstiegsmodul wenn man Informationen zu einem Film sucht. Hinter die Aufruf URL wird einfach der gesuchte Text bzw. Filmtitel gehängt. Die Aufruf URL:

http://ofdbgw.org/search/

Beispiel: http://ofdbgw.org/search/hitch

Filminformationen – Modul “movie”

Das Kernmodul des OFDBGW, mit der aus der Suche zurückgegeben id, lassen sich hiermit die Filminformationen anzeigen über die URL:

http://ofdbgw.org/movie/

Beispiel: http://ofdbgw.org/movie/69878

IMDB ID zu OFDB ID übersetzen – Modul “imdb2ofdb”

Wer bereits eine IMDB ID für einen Film hat, der muss nicht mehr extra über die Suche gehen, sondern kann sich eine IMDB ID auch direkt zu einer OFDB ID übersetzen lassen. Dieses ist möglich da OFDB zu den meisten Filmen auch eine IMDB ID gespeichert hat. Ich habe dafür das Modul IMDB2OFDB entwickelt. Diese ist über die folgende URL erreichbar:

http://ofdbgw.org/imdb2ofdb/

Beispiel: http://ofdbgw.org/imdb2ofdb/tt0386588

Personen Suche – Modul “searchperson”

Wer nicht nur Informationen zu Filmen sondern auch zu Personen sucht, kann dafür das searchperson Modul nutzen. Hier wird als Übergabewert ein Text erwartet der die zu suchende Person enthält. Die Rückgabe ist wieder wie gewöhnlich. Allerdings gibt es verschiedene Suchergebnis Typen, diese sind in den Felder wert und werttyp angegeben. Enthält das Feld werttyp den Inhalt liste, konnte kein passender Eintrag mit eindeutiger ID in der OFDB gefunden werden. Enthält dieser Eintrag jedoch den Wert id, kann man mit dem Ergebnis aus dem Feld wert die Verzweigung in das person Modul machen. Das searchperson Modul ist erreichbar über die URL:

http://ofdbgw.org/searchperson/

Beispiel: http://ofdbgw.org/searchperson/will smith

Personen Informationen – Modul “person”

Mit einer Personen ID z.B. aus dem Modul searchperson oder movie, kann man damit nun das person Modul aufrufen, das ähnlich dem movie Modul alle auffindbaren Informationen zurückgibt. Das person Modul ist erreichbar über die URL:

http://ofdbgw.org/person/

Beispiel: http://ofdbgw.org/person/1136

EAN und UPC Suche – Modul “searchean”

Mit der EAN Suche ist es möglich nach Filmfassungen anhand einer DVD/Blu-Ray zugeordneten EAN bzw. UPC zu suchen. Das Modul ist ähnlich den anderen Such Modulen und erwartet eine EAN oder UPC als Eingabe und ist erreichbar über die URL:

http://ofdbgw.org/searchean/

Beispiel: http://ofdbgw.org/searchean/4030521376748

Fassungen

Diese Modul gib Informationen zu verschiedenen Fassungen von Filmen. Z.B. Kinoversion, DVD, Blu-Ray etc. Das Modul wird mit der Kombination aus FilmID und FassungID getrennt durch ein Semikolon aufgerufen. Die Komplette FassungsID geben z.B. die Module “movie” und “searchean” zurück. Das Modul ist erreichbar über die URL:

http://ofdbgw.org/fassung/

Beispiel: http://ofdbgw.org/fassung/69878;138582

Returncodes

Im Header der XML Datei gibt es immer einen Returncode der über die Verarbeitung aufschluss gib. Hier eine Übersicht, der möglichen Returncodes:

0 = Keine Fehler
1 = Unbekannter Fehler
2 = Fehler oder Timeout bei Anfrage an IMDB bzw. OFDB
3 = Keine oder falsche ID angebene
4 = Keine Daten zu angegebener ID oder Query gefunden
5 = Fehler bei der Datenverarbeitung
9 = Wartungsmodus, OFDBGW derzeit nicht verfügbar.

XML / JSON Return

Standardmässig bekommt man bei allen Anfragen XML Daten zurück. Um die Daten als JSON Datei zu erhaltne muss an alle Aufruf Urls “_json” angehängt werden.

http://ofdbgw.org/search_json/
http://ofdbgw.org/movie_json/
http://ofdbgw.org/imdb2ofdb_json/
http://ofdbgw.org/searchperson_json/
http://ofdbgw.org/person_json/
http://ofdbgw.org/searchean_json/
http://ofdbgw.org/fassung_json/

Beispiel: http://ofdbgw.org/movie_json/69878

Extensionaufruf

Da es bei einigen Parsern zu Problemen kommen kann wenn keine Dateiendung vorhanden ist, gibt es auch noch den Extension aufruf, der es erlaubt alle Module mit einer Dateiendung abzufragen. Der Extensionaufruf wird einfach durchgeführt in dem man “_ext” an das jeweilige Modul mit anhängt.

Aufrufadressen:

http://ofdbgw.org/search_ext/
http://ofdbgw.org/movie_ext/
http://ofdbgw.org/imdb2ofdb_ext/
http://ofdbgw.org/searchperson_ext/
http://ofdbgw.org/person_ext/
http://ofdbgw.org/searchean_ext/
http://ofdbgw.org/fassung_ext/

Das gleiche gilt für die JSON Aufrufe:

http://ofdbgw.org/search_json_ext/
http://ofdbgw.org/movie_json_ext/
http://ofdbgw.org/imdb2ofdb_json_ext/
http://ofdbgw.org/searchperson_json_ext/
http://ofdbgw.org/person_json_ext/
http://ofdbgw.org/searchean_json_ext/
http://ofdbgw.org/fassung_json_ext/

Beispiel:

http://ofdbgw.org/movie_ext/69878.xml
http://ofdbgw.org/movie_json_ext/69878.json

Die Dateiendung ist hier nicht auf “.xml” oder “.json” begrenzt, sondern kann frei gewählt werden und auch eine beliebeige Länge haben, alles vor dem Punkt der Dateiendung wird dann als Anfrage behandelt.

Sollten weitere Fragen zur Nutzung vorhanden sein oder sonstige Wünsche, kontaktiert den derzeitigen Betreiber Tobias Scheeper des Gateways.