Hier finden Sie die deutsche Fassung.


The sightwalk API

The sightwalk API consists of two parts:
  1. Javascript API
    sightwalk is embeddable into arbitrary websites via widget and can be controlled through our API using javascript commands.

  2. Web services
    Web services (REST) provide information to identify those areas covered by sightwalk.


Index
Legal issues

Javascript API
Calling conventions
General usage issues
Reference
Examples

Webservices
Calling conventions
Reference
Examples


Legal issues
The usage of widget and API is restricted by our terms of use.
The required API key can be created free of cost via sightwalk.



sightwalk Javascript/Widget API


Calling convention
Using the sightwalk API is done in three steps:
  1. Referencing the API library
    <script type="text/javascript" src="http://sightwalk.s3.amazonaws.com/core/api/sw_api.js">
  2. Embedding the widget into the site (using API key and a start geoposition)
    <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. Calling single API commands using the SightwalkView object created above.
    ...
    sw.xyz();
    ...

General usage issues

Reference
Current version: 0.11
Below you'll find the data types, events and constants used with the sightwalk widget.

Data types
GeoPos

Geocoordinates (WGS84)

var lat Number latitude
var lon Number longitude

Orientation

View direction for addressing the 3D model

var pan Number Horizontal angle (in degrees 0 bis 359)
var tilt Number Vertical angle (in degrees -60 bis 60)

Address

Addresse for references

var street String Street
var houseNo String (!) House number
var areaCode String Area code, i.e. zip code
var city String City name
var extension String Additional address information
var district String City district

Tag

Container for an embedded icon

var tagId Integer Tag ID
var panoId Integer Pano ID, in which the tag is contained
var name String Tag title
var orientation Orientation 3D-position within the pano
var type Integer Tag category (see constants)
var user String Tag autor's user name
var imgUrl String Picture URL
var contents String Tag description
var geoPos GeoPos Tag position

Pano

A panorama view

var panoId Integer Pano ID
var address Address Pano address
var geoPos GeoPos Pano geocoordinates

SightwalkView

Reference object of the sightwalk Widget

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


Creates the sightwalk widget and embeds it into the HTML DOM model at the desired spot

Parameter:
containerId String Name of the HTML element used as container for the Flash content
apiKey String API Key (available free of charge as registered user via www.sightwalk.de)
width String Width of the widget (applied as style size definition, therefore relative definitions may be used as well)
height String Height of the widget (applied as style size definition, therefore relative definitions may be used as well)
posObj Object May be one or more of the following types: GeoPos, panoId, Address, Orientation

Returns: void

function loadPano (geoPos, orientation)


Loads the panorama which is closest to the given position

Parameter:
geoPos GeoPos Target coordinate
orientation Orientation Initial view

Returns: Integer (see constants)

function loadPano (address, orientation)


Loads the panorama which is closest to the given address

Parameter:
address Address Target address
orientation Orientation Initial view

Returns: Integer (see constants)

function showMessage (message)


Shows a message

Parameter:
message String Message contents

Returns: Integer (see constants)

function getPano ()


Returns the currently shown pano

Parameter: void

Returns: Pano

function getOrientation ()


Returns the current view orientation

Parameter: void

Returns: Orientation

function setOrientation (orientation)


Sets the current view orientation

Parameter:
orientation Orientation View

Returns: Integer (see constants)

function getLink ()


Returns the deeplink URL for the current pano with the actual view orientation. Opening the URL leads to an appropriate view at www.sightwalk.de

Parameter: void

Returns: String

function rotateTo (orientation, seconds)


Rotates the view angle to the target view with the given speed

Parameter:
orientation Orientation View
seconds Integer Time/Speed

Returns: Integer (see constants)

function rotateBy (deltaOrientation)


Rotates the view angle by the given amount

Parameter:
deltaOrientation Orientation View angle

Returns: Integer (see constants)

function getApiVersion ()


Returns the current API version.

Parameter: void

Returns: Number

function setActive (active)


Sets the widget to active resp. inactive state. In inactive state, almost all widget functions are deactivated to reduce CPU consumption.

Parameter:
active Boolean Target state

Returns: Integer (see constants)

function getTags ()


Returns an array of the current pano's tags

Parameter: void

Returns: Tag[]

function showTag (tagId)


Show the given tag's dialog

Parameter:
tagId Integer Tag ID

Returns: Integer (see constants)

function addTag (tag, makePersistent)


Create a new tag

Parameter:
tag Tag The tag to create
makePersistent Boolean If TRUE, the tag will be stored in the database (initially only visible for users of the current API key, after validation by panogate for everyone)

Returns: Integer (see constants)

function addEventListener (eventType, handlerFunction)


Register an event handler

Parameter:
eventType Konstante The event type (see constants)
handlerFunction Function Callback function

Returns: Integer (see constants)

function removeEventHandler (eventType, handlerFunction)


Unregister an event handler

Parameter:
eventType Konstante The event type (see constants)
handlerFunction Function Callback function

Returns: Integer (see constants)

function gotoNextTag (type)


Jump to the closest pano containing a tag of the given type

Parameter:
type Konstante The tag type (see constants)

Returns: Integer (see constants)

function search (city, query)


Returns results for the search query

Parameter:
city String City name
query String Search query

Returns: Integer (see constants)


Events
SightwalkView.EVENT_INITIALIZE
Parameter: void
The Widget has been initialized.


SightwalkView.EVENT_LOADED
Parameter: Pano
The current pano has been loaded completely.


SightwalkView.EVENT_PANO_NOT_FOUND
Parameter: void
For the given parameters no pano could be found.


SightwalkView.EVENT_ORIENTATION_CHANGED
Parameter: Orientation
View angle has changed.


SightwalkView.EVENT_MOUSE_CHANGED
Parameter: Orientation
The mouse cursor view angle has changed (aka "the mouse has been moved").


SightwalkView.EVENT_TAG_CLICKED
Parameter: Tag
Ein Tag wurde angeklickt.


SightwalkView.EVENT_SEARCH_COMPLETE
Parameter: Object[]
The search result is available. It may contain objects of both type Tag and Pano.


SightwalkView.EVENT_GEO_POINTER_CHANGED
Parameter: GeoPos
The mouse cursor points to another geocoordinate (aka "the mouse has been moved"). Using this new view, the geocoordinate by this view angle is returned (5m from the current geoposition)



Constants
Return values


SUCCESS
Value: 0
The action was completed successfully.


ERROR_NOT_INITIALIZED
Value: -1
The widget is not initialized yet.


ERROR_INVALID_ARGS
Value: -2
At least one parameter does not conform with format definitions.


ERROR_EXEC
Value: -3
Error while executing the command.


ERROR_INVALID_APIKEY
Value: -4
No valid API key was definied.


ERROR_SECURITY
Value: -5
Security error (i.e. a specified parameter contains non-valid terms)



Tag types


TAG_BILDUNG
Education
Value: 1


TAG_DIENSTLEISTUNGEN
Services
Value: 2


TAG_FREIZEIT
Leisure, sports
Value: 3


TAG_GASTRONOMIE
Food, restaurants
Value: 4


TAG_FINANCIAL
Financial
Value: 6


TAG_HOTEL
Hotels
Value: 7


TAG_IMMOBILIEN
Real estate, flats for rent
Value: 8


TAG_GESUNDHEIT
Health
Value: 9


TAG_MOBILITAET
Public transport, cabs
Value: 10


TAG_THEATER
Theater
Value: 11


TAG_SHOPPING
Shopping
Value: 12


TAG_NEWS
News
Value: 13


TAG_USER
User-defined tags
Value: 15


TAG_HISTORY
Historical info/pictures
Value: 16


TAG_WIKIPEDIA
Wikipedia
Value: 17


TAG_LAW
Legal institution
Value: 25


TAG_POST
Postal service
Value: 26


TAG_POLIZEI
Police, emergency service
Value: 27


TAG_PARKING
Parking
Value: 28


TAG_CONTAINER
Recycling container
Value: 29


TAG_BARCLUB
Bar, club
Value: 30


TAG_MUSEUM
Museum
Value: 31


TAG_KIRCHE
Church, mosque, synagogue
Value: 32


TAG_ATTRACTION
Attraction, tourist spot
Value: 34


TAG_KINO
Cinema
Value: 35




Examples
The following examples show usage of the defined commands and values.
  1. Embedding the sightwalk widget, positioning via geocoordinates
    <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. Controlling the intialized widget
    <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. Respond to changes
    <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">

    //Start with pano with 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


Calling conventions
Called via HTTP-GET, parameters as querystring. Returns JSON objects.

Reference
Current version: 0.1
Below the web services endpoint are defined.

Endpoints
Retrieval of the closest pano ID for a geocoordinate (WGS84)

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

Parameter:
apiKey String API Key
lat Number Latitude
lon Number Longitude

Returns:
resultCode Integer Success code (see Javascript constants)
panoId Integer ID of the closest pano (only set if resultCode==0)

Retrieval of the closest pano ID for an address

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

Parameter:
apiKey String API Key
street String Street name (Quotes [%27] required, if it contains spaces)
houseNo String House number (optional)
city String City name

Returns:
resultCode Integer Success code (see Javascript constants)
panoId Integer ID of the closest pano (only set if resultCode==0)


Examples
The following examples show usage of the defined endpoints.
  1. Successful call via geocoordinates
    Call:
    http://www.sightwalk.de/api/location?apiKey=1234567890&lat=50.919987&lon=6.927239

    Return:
    {"panoId":87159,"resultCode":0}


  2. Failure call via geocoordinates
    Call:
    http://www.sightwalk.de/api/location?apiKey=1234567890&lat=50.919987&lon=16.927239

    Return:
    {"resultCode":-3}


  3. Successful call via address
    Call:
    http://www.sightwalk.de/api/location?apiKey=1234567890&street='friedrichstr'&houseNo=50&city=berlin

    Return:
    {"panoId":465825,"resultCode":0}