Exchange protocol

= Exchange protocol =

We use "JSON":http://json.org as protocol between client and server. All interaction occur over HTTP. To send request means send HTTP request with needed parameters.

Subscribe channel
Request should be http://your_server/service/subscribe {   "description": "Subscribe to channel", "type": "object", "properties": { "auth_token": {"type":"string"}, "channel":{"type":"string"} } }

Response

{   "description": "response", "type": "object", "properties": { "errno": {"type":"number"} } }

Availablechannels list
Request should be http://your_server/service/channels {     "description": "Avavilable channels", "type": "object", "properties": { "auth_token": {"type":"string"}, "latitude": {"type":"number"}, "longitude": {"type":"number"}, "radius": {"type":"number"} } }

Response with channels list. {   "description": "channels list", "type": "object", "properties": { "errno": {"type":"number"}, "channels": { "type": "array", "items": { "type": "object", "description": "Channel", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type" : "string" } }               }            }        }    } }

Subscribed channels.
Request should be http://your server/service/subscribed {     "description": "Subscribed channels", "type": "object", "properties": { "auth_token": {"type":"string"} } }

Response with channels list. {   "description": "channels list", "type": "object", "properties": { "errno": {"type":"number"}, "channels": { "type": "array", "items": { "type": "object", "description": "Channel", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type" : "string" } }               }            }        }    } }

LoadTags
Load nearest tags, sorted by channels Request should be http://your server/service/loadTags {     "description": "RSS", "type": "object", "properties": { "auth_token": {"type":"string"}, "latitude": {"type":"number"}, "longitude": {"type":"number"}, "radius": {"type":"number"}, "type": {"type":"string", "optinal":true} } }

type:
 * "full" : display all marks, set by default;
 * "last_one" : display last mark, from each channel member

Response with tags {   "description": "rss", "type": "object", "properties": { "errno": {"type":"number"}, "rss": { "type": "object", "properties": { "channel": { "type": "object", "properties": { "title": {"type": "string"}, "link": {"type": "string"}, "description": {"type": "string"}, "language": {"type": "string"}, "pubDate": {"type": "string"}, "item": { "type": "array", "items": { "type": "object", "properties": { "title": {"type": "string"}, "link": {"type": "string"}, "channel": {"type": "string"}, "description": {"type": "string"}, "pubDate": {"type": "string"}, "user": {"type": "string"}, "tags": { "type": "array", "items": {"type": "string"} },                                   "altitude" : {"type": "number"}, "latitude" : {"type": "number"}, "longitude" : {"type": "number"} }                           }                        }                    }                }            }        }    } }

Write tag
Request should be http://your_server/service/writeTag {   "description": "Apply the mark", "type": "object", "properties": { "auth_token": {"type":"string", "can_be_empty": false}, "channel":{"type":"string", "can_be_empty": false}, "title": {"type": "string", "can_be_empty": false}, "link": {"type": "string", "can_be_empty": false}, "description": {"type": "string", "can_be_empty": false}, "latitude": {"type":"number"}, "altitude": {"type":"number"}, "longitude": {"type":"number"}, "time":{"type":"string", "format":"dd MM yyyy HH:mm:ss.zzz"}, } }

More about time specification http://qt-project.org/doc/qt-5.0/qtcore/qdatetime.html#fromString-2.

Response

{   "description": "response", "type": "object", "properties": { "mark_id": {"type":"number"}, "errno": {"type":"number"} } }

BLOBs support
Since version 0.31 Geo2Tag includes experimental blob support. If title starts from \"#BLOB\", than Response will contain guid which can be used for blob reference. See example below: "guid" :       {"type":"string"} "errno":      {"type":"number"}

Apply channel
Request should be http://your server/service/addChannel {   "description": "Add new channel", "type": "object", "properties": { "auth_token": {"type":"string"}, "name":{"type":"string"}, "description": {"type": "string"}, "url": {"type": "string"}, } }

Response

{   "description": "response", "type": "object", "properties": { "errno": {"type":"number"} } }

Unsubscribe channel
Request should be http://your server/service/unsubscribe {   "description": "Unsubscribe to channel", "type": "object", "properties": { "auth_token": {"type":"string"}, "channel":{"type":"string"} } }

Response

{   "description": "response", "type": "object", "properties": { "errno": {"type":"number"} } }

Login
Request should be http://your server/service/login {   "description": "Login", "type": "object", "properties": { "login": {"type":"string"}, "password":{"type":"string"} } }

Response

{   "description": "response", "type": "object", "properties": { "errno": {"type":"number"}, "auth_token": {"type":"string"} } }

Add user
Request should be http://your server/service/addUser

WARNING: This request is  NOT SUPPORTED  anymore!

{   "description": "Add new user", "type": "object", "properties": { "email": {"type":"string"}, "login": {"type":"string"}, "password":{"type":"string"} } }

Response

{   "description": "response", "type": "object", "properties": { "errno": {"type":"number"}, "auth_token": {"type":"string"} } }

Register user
Request should be http://your server/service/registerUser

WARNING: This request is  NOT SUPPORTED  anymore!

{   "description": "Register new user", "type": "object", "properties": { "email": {"type":"string"}, "login": {"type":"string"}, "password":{"type":"string"} } }

Response

{   "description": "response", "type": "object", "properties": { "errno": {"type":"number"}, } }

Quit session
Request should be http://your server/service/quitSession {   "description": "Quit from session", "type": "object", "properties": { "auth_token": {"type":"string"}, } }

Response

{   "description": "response", "type": "object", "properties": { "errno": {"type":"number"}, } }

Circle
Search function like this: list = S (dt, x, y, R), where dt - delta of time; Request should be http://your server/service/filterCircle

Request: {	"description": "CircleFilter", "type": "object", { 		"auth_token":{"type":"string"}, "time_from":{"type":"string"}, "time_to":{"type":"string"}, "longitude":{"type":"number"}, "latitude":{"type":"number"}, "radius":{"type":"number"}, "channel":{ "type":"string", "optinal":true },               "tag_number":{ "type":"number", "optinal":true } 	} }

Response: look at the default filter response (FilterDefaultResponse).

Rectangle
Search function like this: list = S (dt, dx, dy), where dt - delta of time; Request should be http://your server/service/filterRectangle

Request: {	"description": "RectangleFilter", "type": "object", { 		"auth_token":{"type":"string"}, "time_from":{"type":"string"}, "time_to":{"type":"string"}, "latitude_shift": {			"type":"object", {				"latitude1":{"type":"number"}, "latitude2":{"type":"number"}, }

},		"longitude_shift": {			"type":"object", {				"longitude1":{"type":"number"}, "longitude2":{"type":"number"}, }

},               "channel":{ "type":"string", "optinal":true },               "tag_number":{ "type":"number", "optinal":true } 	} }

Response: look at the default filter response (FilterDefaultResponse).

Polygon
Search function like this: list = S (dt, list), where dt - delta of time; Request should be http://your server/service/filterPolygon

Request: {	"description": "PoligonFilter", "type": "object", { 		"auth_token":{"type":"string"}, "time_from":{"type":"string"}, "time_to":{"type":"string"}, "polygon": {			"type":"array", {				"number":{"type":"number"}, "latitude":{"type":"number"}, "longitude":{"type":"number"} }		},               "channel":{ "type":"string", "optinal":true },               "tag_number":{ "type":"number", "optinal":true } 	} }

Response: look at the default filter response (FilterDefaultResponse).

Cylinder
Search function like this: list = S (dt, x, y, R, dh), where dt - delta of time, dh - delta of height; Request should be http://your server/service/filterCylinder

Request: {	"description": "CylinderFilter", "type": "object", { 		"auth_token":{"type":"string"}, "time_from":{"type":"string"}, "time_to":{"type":"string"}, "radius":{"type":"number"}, "longitude":{"type":"number"}, "latitude":{"type":"number"}, "altitude_shift": {			"type":"object", {				"altitude1":{"type":"number"}, "altitude2":{"type":"number"}, }		},               "channel":{ "type":"string", "optinal":true },               "tag_number":{ "type":"number", "optinal":true } 	} }

Response: look at the default filter response (FilterDefaultResponse).

Box
Search function like this: list = S (dt, dx, dy, dz), where dt - delta of time, dh - delta of height; Request should be http://your server/service/filterBox

Request: {	"description": "Box", "type": "object", { 		"auth_token":{"type":"string"}, "time_from":{"type":"string"}, "time_to":{"type":"string"}, "latitude_shift": {			"type":"object", {				"latitude1":{"type":"number"}, "latitude2":{"type":"number"}, }

},		"longitude_shift": {			"type":"object", {				"longitude1":{"type":"number"}, "longitude2":{"type":"number"}, }

}		"altitude_shift": {			"type":"object", {				"altitude1":{"type":"number"}, "altitude2":{"type":"number"}, }		},               "channel":{ "type":"string", "optinal":true },               "tag_number":{ "type":"number", "optinal":true } 	} }

Response: look at the default filter response (FilterDefaultResponse).

Fence
Search function like this: list = S (dt, list, dh), where dt - delta of time, dh - delta of height; Request should be http://your server/service/filterFence

Request: {	"description": "Fence", "type": "object", { 		"auth_token":{"type":"string"}, "time_from":{"type":"string"}, "time_to":{"type":"string"}, "polygon": {			"type":"array", {				"number":{"type":"number"}, "latitude":{"type":"number"}, "longitude":{"type":"number"} }		},		"altitude_shift": {			"type":"object", {				"altitude1":{"type":"number"}, "altitude2":{"type":"number"}, }		},               "channel":{ "type":"string", "optinal":true },               "tag_number":{ "type":"number", "optinal":true } 	} }

Response: look at the default filter response (FilterDefaultResponse).

FilterDefaultResponse - Common response for all filtration requests (default filter response).
List of tags Response: {	"description": "TagList", "type": "object", {	"errno":{"type":"number"}, "channels": {		"type": "array", "channel": {			"type": "array", "items": {				"title": {"type": "string"}, "link": {"type": "string"}, "channel": {"type": "string"}, "description": {"type": "string"}, "pubDate": {"type": "string"}, "user": {"type": "string"}, "latitude" : {"type": "number"}, "longitude" : {"type": "number"}, "altitude":{"type":"number"} } 			}		}	} }

FilterChannel
Return given amount of tags from given chanel.

Request should be http://your server/service/filterChannel {   "description": "Get given amount of tags from the channel", "type": "object", "properties": { "auth_token": {"type":"string"}, "channel": {"type":"string"}, "amount": {"type":"integer"}, } }

Response: {	"description": "TagList", "type": "object", {	"errno":{"type":"number"}, "channel": {		"type": "array", "name": {"type": "string"}, "channel": {			"type": "array", "items": {				"title": {"type": "string"}, "link": {"type": "string"}, "channel": {"type": "string"}, "description": {"type": "string"}, "pubDate": {"type": "string"}, "user": {"type": "string"}, "latitude" : {"type": "number"}, "longitude" : {"type": "number"}, "altitude":{"type":"number"} } 			}		}	} }

FilterSubstring
Return tags which fields contains specified substring.

Request should be http://your server/service/filterSubstring {   "description": "Filter", "type": "object", "properties": { "auth_token": {"type":"string"}, "field": { "type":"string", "values":["url", "label", "description"] },       "substring" : {"type":"string"}, "tag_number": { "type":"integer", "optinal":true },   } }

Return platform version
Request no request data needed. Just perform GET request to http://your server/service/version

Response

{   "description": "response", "type": "object", "properties": { "errno": {"type":"number"}, "version": {"type":"string"} } }

Return platform build(commit hash and number)
Request no request data needed. Just perform GET request to http://your server/service/build

Response

{   "description": "response", "type": "object", "properties": { "errno": {"type":"number"}, "version": {"type":"string"} } }

SetDB
Request should be http://your server/service/setdb {   "description": "SetDB", "type": "object", "properties": { "auth_token": {"type":"string"}, "db_name":{"type":"string"} } }

Response

{   "description": "response", "type": "object", "properties": { "errno": {"type":"number"} } }

Alter channel
Request should be http://your server/service/alterChannel {   "description": "Alter channel", "type": "object", "properties": { "auth_token": {"type":"string"}, "name":{"type":"string", "description":"channel name"}, "field":{"type":"string", "description":"channel field to change: url, name or description"}, "value":{"type":"string", "description":"new field value"} } }

Response

{   "description": "response", "type": "object", "properties": { "errno": {"type":"number"} } }

Change password
Request should be http://your_server/service/changePassword {   "description": "Change user password", "type": "object", "properties": { "login": {"type":"string"}, "password":{"type":"string", "description":"old password"}, "new_password":{"type":"string", "description":"new password"} } }

Response

{   "description": "response", "type": "object", "properties": { "errno": {"type":"number"} } }

Write blob for tag
Request should be http://your_server/service/setBlob: { "auth_token": {"type":"string"}, "guid":      {"type":"string"}, "blob":      {"type":"string"} } where blob is BASE64 coded binary

Response "errno":     {"type":"number"}

Getting blob for tag
Request should be http://your_server/service/getBlob

"auth_token": {"type":"string"}, "guid": {"type":"string"}

Response {  "errno":      {"type":"number"}, "blob":      {"type":"string"} }

where blob is BASE64 coded binary

= How it can be tested =

You can write your own application or use curl for it. The way with curl described here

Overview results / questions