Please follow this link for the English version.


Die sightwalk-API

Die sightwalk API besteht aus zwei Teilen:
  1. Javascript API
    sightwalk lässt sich per Widget in beliebige HTML-Webseiten einbetten und über unsere API mittels Javascript-Befehlen steuern.

  2. Webservices
    Zur Identifikation derjenigen Bereiche, die in sightwalk abgebildet sind, existieren Webservices (REST).


Index
Rechtliches

Javascript API
Aufruf
Grundsätzliche Hinweise zur Verwendung
Referenz
Beispiele

Webservices
Aufruf
Referenz
Beispiele


Rechtliches
Die Verwendung von Widget und der API unterliegt folgenden Nutzungsbedingungen
Ein API-Schlüssel kann kostenlos via sightwalk erzeugt werden.



sightwalk Javascript/Widget API


Aufruf
Die Nutzung von sightwalk per API erfolgt in drei Schritten:
  1. Referenzierung der API-Bibliothek
    <script type="text/javascript" src="http://sightwalk.s3.amazonaws.com/core/api/sw_api.js">
  2. Einbettung des Widgets in die Seite (unter Angabe des API-Schlüssels und einer Start-Position)
    <div id="swContainer"/>
    ...
    <script type="text/javascript">

    var a = new Address();
    a.street = "Apostelnstr";
    a.houseNo = "25";
    a.city = "Köln";

    var sw = new SightwalkView("swContainer", "123456789012345678901234567890", "100%","100%", a);

    </script>
  3. Aufruf einzelner API-Befehle unter Verwendung des oben erzeugten SightwalkView-Objektes
    ...
    sw.xyz();
    ...

Grundsätzliche Hinweise zur Verwendung

Referenz
Aktuelle Version: 0.11
Nachfolgend werden die Datentypen, Events und Konstanten dargestellt, mittels denen sich das sightwalk-Widget steuern lässt.

Datentypen
GeoPos

Geokoordinate für Adressierungen (WGS84)

var lat Number Längengrad
var lon Number Breitengrad

Orientation

Blickrichtung für Adressierungen im 3D-Modell

var pan Number Horizontaler Winkel (in Grad 0 bis 359)
var tilt Number Vertikaler Winkel (in Grad -60 bis 60)

Address

Adresse für Referenzen

var street String Straße
var houseNo String (!) Hausnummer
var areaCode String Postleitzahl
var city String Stadt
var extension String Adress-Zusatz
var district String Stadtteil

Tag

Platzhalter für ein eingebettetes Icon

var tagId Integer ID des Tags
var panoId Integer ID des Panos, in dem sich das Tag befindet
var name String Dargestellter Titel des Tags
var orientation Orientation 3D-Position innerhalb des Panos
var type Integer Kategorie des Tags (siehe Konstanten)
var user String Benutzername des Tag-Autors
var imgUrl String URL des jeweiligen Bildes
var contents String Beschreibung des Tags
var geoPos GeoPos Position des Tags

Pano

Eine Panorama-Ansicht

var panoId Integer ID des Panos
var address Address Adresse des Panos
var geoPos GeoPos Position des Panos

SightwalkView

Referenz-Objekt für das sightwalk-Widget

function SightwalkView (containerId, apiKey, width, height, posObj...)


Erzeugt das sightwalk-Widget und bettet es an angegebener Stelle in die aktuelle HTML-Seite ein

Parameter:
containerId String Name des HTML-Elements, das als Container für den Flash-Content fungieren soll
apiKey String API-Schlüssel (kostenlos erhältlich als registrierter Benutzer via www.sightwalk.de)
width String Breite des Widgets (wird als Style-Größenangabe verwendet, daher sind auch prozentuale Angaben möglich)
height String Höhe des Widgets (wird als Style-Größenangabe verwendet, daher sind auch prozentuale Angaben möglich)
posObj Object Dabei kann es sich entweder um ein oder mehrere der folgenden Typen handeln: GeoPos, panoId, Address, Orientation

Rückgabewert: void

function loadPano (geoPos, orientation)


Lädt das Panorama, welches sich am nächsten an der angegebenen Position befindet

Parameter:
geoPos GeoPos Ziel-Koordinate
orientation Orientation Initialer Blickrichtung

Rückgabewert: Integer (siehe Konstanten)

function loadPano (address, orientation)


Lädt das Panorama, welches sich am nächsten an der angegebenen Adresse befindet

Parameter:
address Address Ziel-Adresse
orientation Orientation Initialer Blickrichtung

Rückgabewert: Integer (siehe Konstanten)

function showMessage (message)


Zeigt die angebenene Nachricht an

Parameter:
message String Nachricht

Rückgabewert: Integer (siehe Konstanten)

function getPano ()


Liefert das aktuell angezeigte Pano zurück

Parameter: void

Rückgabewert: Pano

function getOrientation ()


Liefert die aktuelle Blickrichtung zurück

Parameter: void

Rückgabewert: Orientation

function setOrientation (orientation)


Setzt die aktuelle Blickrichtung

Parameter:
orientation Orientation Blickwinkel

Rückgabewert: Integer (siehe Konstanten)

function getLink ()


Liefert die DeepLink-URL zum aktuellen Pano samt aktuellem Blickrichtung zurück. Diese URL führt zu einer entsprechenden Ansicht auf www.sightwalk.de

Parameter: void

Rückgabewert: String

function rotateTo (orientation, seconds)


Rotiert in angegebener Geschwindigkeit zum Ziel-Blickwinkel

Parameter:
orientation Orientation Blickwinkel
seconds Integer Zeit/Geschwindigkeit

Rückgabewert: Integer (siehe Konstanten)

function rotateBy (deltaOrientation)


Rotiert den Blickwinkel um die angegebene Größe

Parameter:
deltaOrientation Orientation Blickwinkel

Rückgabewert: Integer (siehe Konstanten)

function getApiVersion ()


Liefert die aktuelle Versions-Nummer der API zurück

Parameter: void

Rückgabewert: Number

function setActive (active)


Versetzt das Widget in aktiven bzw. inaktiven Zustand. Im inaktiven Zustand werden zur Verringerung des Resourcenverbrauchs fast alle Widget-Funktionen deaktiviert.

Parameter:
active Boolean Soll-Zustand

Rückgabewert: Integer (siehe Konstanten)

function getTags ()


Liefert ein Array der Tags des aktuellen Panos zurück

Parameter: void

Rückgabewert: Tag[]

function showTag (tagId)


Ruft die Anzeige des angegebenen Tags auf

Parameter:
tagId Integer ID des Tags

Rückgabewert: Integer (siehe Konstanten)

function addTag (tag, makePersistent)


Erzeugt ein neues Tag

Parameter:
tag Tag Das zu erzeugende Tag
makePersistent Boolean Falls TRUE, wird das Tag in den Datenbestand übernommen (zunächst nur sichtbar für Nutzer des verwendeten API-Schlüssels, nach Prüfung ggf. für alle)

Rückgabewert: Integer (siehe Konstanten)

function addEventListener (eventType, handlerFunction)


Registriert einen Event-Handler

Parameter:
eventType Konstante Der Event-Typ (siehe Konstanten)
handlerFunction Function Callback-Funktion

Rückgabewert: Integer (siehe Konstanten)

function removeEventHandler (eventType, handlerFunction)


De-registriert einen Event-Handler

Parameter:
eventType Konstante Der Event-Typ (siehe Konstanten)
handlerFunction Function Callback-Funktion

Rückgabewert: Integer (siehe Konstanten)

function gotoNextTag (type)


Springt zum nächstliegenden Pano, in welchem sich ein Tag des angegebenen Typs befindet

Parameter:
type Konstante Der Tag-Typ (siehe Konstanten)

Rückgabewert: Integer (siehe Konstanten)

function search (city, query)


Findet Ergebnisse zum Suchbegriff

Parameter:
city String Stadt
query String Suchbegriff

Rückgabewert: Integer (siehe Konstanten)


Events
SightwalkView.EVENT_INITIALIZE
Parameter: void
Das Widget wurde initialisiert.


SightwalkView.EVENT_LOADED
Parameter: Pano
Das aktuelle Pano wurde vollständig geladen.


SightwalkView.EVENT_PANO_NOT_FOUND
Parameter: void
Zur vorgegebenen Adressierung konnte kein Pano gefunden werden.


SightwalkView.EVENT_ORIENTATION_CHANGED
Parameter: Orientation
Die Blickrichtung hat sich geändert.


SightwalkView.EVENT_MOUSE_CHANGED
Parameter: Orientation
Der Mauszeiger zeigt auf eine andere Blickrichtung (aka "die Maus wurde bewegt").


SightwalkView.EVENT_TAG_CLICKED
Parameter: Tag
Ein Tag wurde angeklickt.


SightwalkView.EVENT_SEARCH_COMPLETE
Parameter: Object[]
Das Suchergebnis liegt vor. Dabei handelt es sich sowohl um Objekte vom Typ Tag als auch Pano.


SightwalkView.EVENT_GEO_POINTER_CHANGED
Parameter: GeoPos
Der Mauszeiger zeigt auf eine andere Blickrichtung (aka "die Maus wurde bewegt"). Anhand dieser neuen Blickrichtung wird die dort (in 5m Abstand) liegende Geokoordinate zurückgeliefert.



Konstanten
Rückgabewerte


SUCCESS
Wert: 0
Die Aktion wurde erfolgreich abgeschlossen.


ERROR_NOT_INITIALIZED
Wert: -1
Das Widget ist noch nicht initialisiert.


ERROR_INVALID_ARGS
Wert: -2
Mindestens ein Parameter entspricht nicht den Vorgaben.


ERROR_EXEC
Wert: -3
Fehler bei der Ausführung der Aktion.


ERROR_INVALID_APIKEY
Wert: -4
Es wurde kein gültiger API-Schlüssel übergeben.


ERROR_SECURITY
Wert: -5
Sicherheitsfehler (z.B. ein übergebener Parameter enthält nicht-gültige Begriffe)



Tag-Typen


TAG_BILDUNG
Wert: 1


TAG_DIENSTLEISTUNGEN
Wert: 2


TAG_FREIZEIT
Wert: 3


TAG_GASTRONOMIE
Wert: 4


TAG_FINANCIAL
Wert: 6


TAG_HOTEL
Wert: 7


TAG_IMMOBILIEN
Wert: 8


TAG_GESUNDHEIT
Wert: 9


TAG_MOBILITAET
Wert: 10


TAG_THEATER
Wert: 11


TAG_SHOPPING
Wert: 12


TAG_NEWS
Wert: 13


TAG_USER
Wert: 15


TAG_HISTORY
Wert: 16


TAG_WIKIPEDIA
Wert: 17


TAG_LAW
Wert: 25


TAG_POST
Wert: 26


TAG_POLIZEI
Wert: 27


TAG_PARKING
Wert: 28


TAG_CONTAINER
Wert: 29


TAG_BARCLUB
Wert: 30


TAG_MUSEUM
Wert: 31


TAG_KIRCHE
Wert: 32


TAG_ATTRACTION
Wert: 34


TAG_KINO
Wert: 35




Beispiele
Nachfolgend zeigen mehrere Beispiele die Verwendung der beschriebenen Funktionen und Werte.
  1. Einbindung des sightwalk-Widgets, Positionierung über Geo-Koordinaten
    <html>
    <head>
    <script type="text/javascript" src="http://sightwalk.s3.amazonaws.com/core/api/sw_api.js">
     <style type="text/css">
    #swContainer {width:600px;height:600px;}
    </style>
    </head>
    <body>
    <div id="swContainer"></div>
    <script type="text/javascript">

    var g = new GeoPos(50.9279333333333, 6.94373333333333);

    var sw = new SightwalkView("swContainer", "123456789012345678901234567890", "100%","100%", g);
     </script>
    </body>
    </html>

  2. Steuerung des intialisierten Widgets
    <html>
    <head>
    <script type="text/javascript" src="http://sightwalk.s3.amazonaws.com/core/api/sw_api.js">
     <style type="text/css">
    #swContainer {width:600px;height:600px;}
    </style>
    </head>
    <body>
    <div id="swContainer"></div>
    <script type="text/javascript">

    var a = new Address();
    a.street = "Apostelnstr";
    a.houseNo = "25";
    a.city = "Köln";

    var sw = new SightwalkView("swContainer", "123456789012345678901234567890", "100%","100%", a);

    sw.addEventListener(SightwalkView.EVENT_INITIALIZE, onSwInit);
    function onSwInit()
    {
    sw.showMessage("hello sightwalk!");
    }

     </script>
    </body>
    </html>

  3. Reagieren auf Veränderungen
    <html>
    <head>
    <script type="text/javascript" src="http://sightwalk.s3.amazonaws.com/core/api/sw_api.js">
     <style type="text/css">
    #swContainer {width:600px;height:600px;}
    </style>
    </head>
    <body>
    <div id="swContainer"></div>
    <p id="output" />
    <p id="output2" />
    <script type="text/javascript">

    //Starte mit Pano mit ID 12345
    var sw = new SightwalkView("swContainer", "123456789012345678901234567890", "100%","100%", 12345);

    sw.addEventListener(SightwalkView.EVENT_MOUSE_CHANGED, onMouseChanged);
    function onMouseChanged(params)
    {
    document.getElementById("output").innerHTML = "Maus: " + params.pan + "/" + params.tilt + "°";
    }

    sw.addEventListener(SightwalkView.EVENT_ORIENTATION_CHANGED, onSwChanged);
    function onSwChanged(params)
    {
    document.getElementById("output2").innerHTML = "Pano: " + params.pan + "/" + params.tilt + "°";
    }

     </script>
    </body>
    </html>



sightwalk Webservices API


Aufruf
Aufruf via HTTP-GET, Parameter als Querystring. Die Rückgabe erfolgt via JSON-Objekte.

Referenz
Aktuelle Version: 0.1
Nachfolgend werden die Endpunkte der sightwalk Webservices definiert.

Endpunkte
Abfrage der nächstgelegenen Pano-ID anhand Geokoordinate (WGS84)

http://www.sightwalk.de/api/location?apiKey=abc&lat=50.919987&lon=6.927239

Parameter:
apiKey String API-Schlüssel
lat Number Längengrad
lon Number Breitengrad

Rückgabewerte:
resultCode Integer Erfolgs-Anzeige (siehe Javascript-Konstanten)
panoId Integer ID des nächstgelegenen Panos (nur gesetzt falls resultCode==0)

Abfrage der nächstgelegenen Pano-ID anhand Adresse

http://www.sightwalk.de/api/location?apiKey=abc&street='Friedrichstr.'&houseNo=50&city=Berlin

Parameter:
apiKey String API-Schlüssel
street String Straßenname (Anführungszeichen [%27] erforderlich, falls Leerzeichen enthalten)
houseNo String Hausnummer (optional)
city String Name der Stadt

Rückgabewerte:
resultCode Integer Erfolgs-Anzeige (siehe Javascript-Konstanten)
panoId Integer ID des nächstgelegenen Panos (nur gesetzt falls resultCode==0)


Beispiele
Nachfolgend zeigen mehrere Beispiele die Verwendung der beschriebenen Endpunkte.
  1. Erfolgreiche Abfrage anhand Geokoordinaten
    Aufruf:
    http://www.sightwalk.de/api/location?apiKey=1234567890&lat=50.919987&lon=6.927239

    Rückgabe:
    {"panoId":87159,"resultCode":0}


  2. Erfolglose Abfrage anhand Geokoordinaten
    Aufruf:
    http://www.sightwalk.de/api/location?apiKey=1234567890&lat=50.919987&lon=16.927239

    Rückgabe:
    {"resultCode":-3}


  3. Erfolgreiche Abfrage anhand Adresse
    Aufruf:
    http://www.sightwalk.de/api/location?apiKey=1234567890&street='friedrichstr'&houseNo=50&city=berlin

    Rückgabe:
    {"panoId":465825,"resultCode":0}