Developer API - KISS Engine

BETA

Synopsis

The following API calls are demonstrated using the wget command-line utility from Linux - but you can make these HTTP calls with your favourite language instead. Search uses GET and all other requests use POST.

In examples where XML is used in the 'data' field, you can also choose to use JSON or CSV instead. See the 'format' field for how to specify this. We recommend either XML or JSON, however.

NOTE: you should not publicly disclose your key. For instance, if you intend to perform one of the POST request calls within javascript in a client-side web browser, you should first create a small server-side script to perform the call which uses your key, and call that from within javascript, instead of directly calling the nakdreality service.

Search for points in the KISS testbed (from Timbuktu) with a search query of "test search"

Search for points in the KISS testbed (from Timbuktu) without a search query

Insert a point into the testbed: e.g. add a new person (name = Joe Bloggs) using the social API, and check them into a new venue (latitude 16.775, longitude -3.025) near Timbuktu:

Update a point on the testbed: e.g. change "Joe Bloggs", who the response said was personID 0000000001, to "Jim Bloggs"

Delete a point on the testbed: e.g. remove person "Joe Bloggs" (Which will also remove their checkins. To keep the person and remove their checkin, use the checkinID instead of the personID in the delete data.)

Upload an image to the testbed: (Note the fake image data XXXXXX - this needs to come via a multi-part POST file upload form)

Select a point from the testbed:

Description

CGI parameters for searching (based on the Layar GetPOIs format)

The output from a search API call uses the JSON Layar response format as documented by AR company Layar. This allows our output to be viewed by the augmented reality Layar mobile phone app

CGI parameters for insert, update, delete, select, and upload

The data parameter should be serialised data in your chosen format (json, xml, or csv) for the particular API you are using (social, document, or shopping)

There is a current size limit of 10M for any one insert command, so larger inserts should be cut into smaller chunks of 10M each.

Data content fields: (by API)

Social API

The social API features three sets of objects: people, venues, and checkins.

	Venue fields:
	    'venueID'
	    'venue'
	    'address'
	    'phone'
	    'description'
	    'latitude'
	    'longitude'
	    'accuracy'
	    'venueTime'

	Person fields:
	    'personID'
	    'published'
	    'url'
	    'name'
	    'information'
	    'rating'
	    'rating2'
	    'barcode'
	    'imageUrl'
	    'category'
	    'url2'
	    'url3'
	    'personTime'

	Checkin fields:
	    'checkinID'
	    'personID'
	    'venueID'
	    'checkinTime'

	Image fields:
	    'scale_width'
	    'scale_height'

Document API

The document API features three sets of objects: documents, locations, and copies.

	Location fields:
	    'locationID'
	    'name'
	    'address'
	    'phone'
	    'hours'
	    'latitude'
	    'longitude'
	    'accuracy'
	    'locationTime'

	Document fields:
	    'documentID'
	    'published'
	    'url'
	    'title'
	    'description'
	    'price'
	    'price2'
	    'barcode'
	    'imageUrl'
	    'category'
	    'url2'
	    'url3'
	    'documentTime'	

	Copy fields:
	    'copyID'
	    'documentID'
	    'locationID'
	    'copyTime'

	Image fields:
	    'scale_width'
	    'scale_height'

Shopping API

The shopping API features three sets of objects: shops, products, and stock.

	Shop fields:
	    'storeID'
	    'name'
	    'address'
	    'phone'
	    'hours'
	    'latitude'
	    'longitude'
	    'accuracy'
	    'storeTime'

	Product fields:
	    'productID'
	    'published'
	    'url'
	    'title'
	    'description'
	    'price'
	    'priceBeforeSale'
	    'salesCode'
	    'imageUrl'
	    'category'
	    'reserveProductUrl'
	    'checkAvailabilityUrl'
	    'productTime'

	Stock fields:
	    'stockID'
	    'productID'
	    'storeID'
	    'stockTime'

	Image fields:
	    'scale_width'
	    'scale_height'

The output from a successful insert consists of a data file in the same format as the input. For example after using insert to add a person with the social API in XML format, the output will look like:

<?xml version="1.0" encoding="UTF-8"?>
<response>
<results>
<checkinID>2</checkinID>
<personID>0000000001</personID>
<venueID>0000000001</venueID>
</results>
</response>

Data fields for 'export'

The output of an export will look like: (e.g. XML)

<?xml version="1.0" encoding="UTF-8"?>
<response>
<results>
<header>1</header>
<finishedAt>2</finishedAt>
<recordsExported>2</recordsExported>
</results>
<results>
<latitude>51.23456</latitude>
<longitude>-1.23456</longitude>
<title>I woz here</title>
</results>
<results>
<latitude>52.65432</latitude>
<longitude>-1.43210</longitude>
<title>I woz here too</title>
</results>
</response>

The export API service has been designed for clarity rather than efficiency, so please contact us if you have more demanding requirements, and we can make other arrangements

Data fields for 'signup'

The output of a successful signup will look like: (e.g. XML)

<?xml version="1.0" encoding="UTF-8"?>
<response>
<results>
<userID>K1tJikgxGDFoDa9</userID>
<sessionID>ObX9H5HUoGxhcFTRpxsRG1ukCNzMVw6Z</sessionID>
</results>
</response>

The output of an unsuccessful signup could look like: (e.g. XML)

<?xml version="1.0" encoding="UTF-8"?>
<response>
<errors>Your email address has already been taken!</errors>

Possible errors for 'signup'

Data fields for 'login'

The output of a successful login will look like: (e.g. XML)

<?xml version="1.0" encoding="UTF-8"?>
<response>
<results>
<userID>K1tJikgxGDFoDa9</userID>
<sessionID>ObX9H5HUoGxhcFTRpxsRG1ukCNzMVw6Z</sessionID>
</results>
</response>

An unsuccessful login will look like:

<?xml version="1.0" encoding="UTF-8"?>
<response>
<results>
</results>
</response>

Sessions currently expire after 48 hours of inactivity. This value is subject to review.

There is a limit of 10 consecutive unsuccessful logins for a given user before their account is automatically suspended.

Data fields for 'captcha' when generating a captcha:

Data fields for 'captcha' when matching a captcha

Data fields returned when matching a captcha

Gets or sets flexible field/value data associated with a particular user:

• If you include a 'value' it will do a 'set'.
• If you do not include a 'value' it will do a 'get'.
• If you include no 'field' or 'value' then it will 'get' all fields and values.

Data fields for 'user'

Data fields returned from 'user' gets

Possible errors for 'user'

Authenicates a user's session, based on their userID and sessionID (as previously returned from the 'login' or 'signup' service).

Data fields for 'authenticate'

Data fields returned from 'authenticate'