Geospatial & GeoIp decoding Service

A geospatial management service on West Connectivity based on Redis geo commands

Operations

• Geo.addFenceEvent() - Add a fence event into a group item
• Geo.distance() - Calculate the distance between two position
• Geo.fetchNearbyCursor() - Fetch the result in the cursor from a nearby operation
• Geo.geoToAddress() - Get the address information by geo location
• Geo.getFence() - Get specific the fence
• Geo.getGroupItem() - Get the item with the coordinates info through the given identity
• Geo.getGroupItems() - Get the items with the coordinates info through the given identities
• Geo.inside() - Check if a target is inside the fence
• Geo.ipToGeo() - Get the geo information by ip
• Geo.listFenceEvents() - list all fence events through a given group item
• Geo.listFences() - list all fences
• Geo.nearby() - Search the items within the given center and radius
• Geo.removeAll() - remove all data stored in Geo service
• Geo.removeFence() - Remove specific the fence
• Geo.removeFenceEvent() - Remove a fence event
• Geo.removeGroup() - Remove the group includes all items in this group
• Geo.removeGroupItem() - Remove the item from a group
• Geo.removeNearbyCursor() - Remove the cursor of the result from a nearby operation
• Geo.setFence() - Set the fence with the polygon or circle
• Geo.setGroupItem() - Set a item with the coordinates in the group.

Events

• fence - Event message sent by Geo service

---

Operations

Please note that bold arguments are required, while italic arguments are optional.

addFenceEvent

Add a fence event into a group item

Arguments

parameters (object) - Object containing service call parameters.

Name	Type	Description
fence	string	Fence name
group	string	Group name
idlist	[ string ]	List id of group items
inside	boolean	Inside of the fence or not
duration	integer	Duration of the fence detection Minimum: 1

Responses

Code	Body Type	Description
204	nil	Ok
default	object	Service error

Object Parameter of default response:

Name	Type	Description
error	string	Error message
status	"100", "101", "200", "201", "202", "203", "204", "205", "206", "300", "301", "302", "303", "304", "305", "307", "400", "401", "402", "403", "404", "405", "406", "407", "408", "409", "410", "411", "412", "413", "414", "415", "416", "417", "500", "501", "502", "503", "504", "505"	Http status code

Example

local ret = Geo.addFenceEvent({
  group = "device",
  idlist = {
    "sn001",
    "sn002"
  },
  fence = "myPolygon",
  inside = true,
  duration = 5
})

distance

Calculate the distance between two position

Arguments

parameters (object) - Object containing service call parameters.

Name	Type	Description
src	string	Group id of the source
dest	string	Group id of the source
unit	"m", "km", "mi", "ft"	Unit Default: "m"
group	string	Group name

Responses

Code	Body Type	Description
200	nil	The distance
default	object	Service error

Object Parameter of default response:

Name	Type	Description
error	string	Error message
status	"100", "101", "200", "201", "202", "203", "204", "205", "206", "300", "301", "302", "303", "304", "305", "307", "400", "401", "402", "403", "404", "405", "406", "407", "408", "409", "410", "411", "412", "413", "414", "415", "416", "417", "500", "501", "502", "503", "504", "505"	Http status code

Example

local ret = Geo.distance({
  dest = "sn008",
  group = "device",
  src  = "sn001",
  unit = "km"
})
if ret.error ~= nil then
  return ret.error
end
print(ret.value)
-- [expected return]
-- 123.45 (positive float value)

fetchNearbyCursor

Fetch the result in the cursor from a nearby operation

Arguments

parameters (object) - Object containing service call parameters.

Name	Type	Description
key	string	Id of the cache after nearby
limit	integer	Amount data of one page
match	string	Redis match string
cursor	integer	To fetch next page of result until meet 0

Responses

Code	Body Type	Description
200	nil	Include next cursor and fetched items
default	object	Service error

Object Parameter of default response:

Name	Type	Description
error	string	Error message
status	"100", "101", "200", "201", "202", "203", "204", "205", "206", "300", "301", "302", "303", "304", "305", "307", "400", "401", "402", "403", "404", "405", "406", "407", "408", "409", "410", "411", "412", "413", "414", "415", "416", "417", "500", "501", "502", "503", "504", "505"	Http status code

Example

local ret = Geo.fetchNearbyCursor({
  key = websocket_info.socket_id,
  cursor = 0,
  limit = 200
})
return ret.value.items

geoToAddress

Get the geo information by geo location

Arguments

parameters (object) - Object containing service call parameters.

Name	Type	Description
zoom	integer	Level of detail required where 0 is country and 18 is house/building Maximum: 18
language	string	Language to format
extratags	boolean	Output extra tags or not
useragent	string	Custom user-agent header for geoToAddress
coordinates	[ number ]	Coordinates
namedetails	boolean	Output name detail or not
addressdetails	boolean	Output name detail or not

Responses

Code	Body Type	Description
200	nil	Include latitude, longitude, country, city, state, zipcode, streetName, countryCode ... etc.
default	object	Service error

Object Parameter of default response:

Name	Type	Description
error	string	Error message
status	"100", "101", "200", "201", "202", "203", "204", "205", "206", "300", "301", "302", "303", "304", "305", "307", "400", "401", "402", "403", "404", "405", "406", "407", "408", "409", "410", "411", "412", "413", "414", "415", "416", "417", "500", "501", "502", "503", "504", "505"	Http status code

Example

local ret = Geo.geoToAddress({
  coordinates = {-93.2888067, 44.9802115}
})
if ret.error ~= nil then
  return ret.error
end
print(ret.value)
-- [expected return]
-- {
-- "zipcode":"55405",
-- "streetName":"Market Street",
-- "streetNumber":"275",
-- "latitude":44.979988,
-- "longitude":-93.28877323073266,
-- "formattedAddress":"International Market Square, 275, Market Street, Sumner - Glenwood, Minneapolis, Hennepin County, Minnesota, 55405, United States",
-- "provider":"openstreetmap",
-- "countryCode":"US",
-- "city":"Minneapolis",
-- "neighbourhood":"Sumner - Glenwood",
-- "state":"Minnesota",
-- "country":"United States"
-- }

getFence

Get specific the fence

Arguments

parameters (object) - Object containing service call parameters.

Name	Type	Description
fence	string	Fence name

Responses

Code	Body Type	Description
200	nil	Include fence and shape
default	object	Service error

Object Parameter of default response:

Name	Type	Description
error	string	Error message
status	"100", "101", "200", "201", "202", "203", "204", "205", "206", "300", "301", "302", "303", "304", "305", "307", "400", "401", "402", "403", "404", "405", "406", "407", "408", "409", "410", "411", "412", "413", "414", "415", "416", "417", "500", "501", "502", "503", "504", "505"	Http status code

Example

local ret = Geo.getFence({
  fence = "hotzone",
})
if ret.error ~= nil then
  return ret.error
end
print(ret.value)
-- [expected return]
-- {
-- "status":200,
-- "value":{
--   "polygon":[[1,10],[1,2],[8,1],[2,2]],
--   "fence":"hotzone"}
-- }

getGroupItem

Get the item with the coordinates info through the given identity

Arguments

parameters (object) - Object containing service call parameters.

Name	Type	Description
id	string	Id of group item
group	string	Group name

Responses

Code	Body Type	Description
200	nil	Include id, coordinates and item
default	object	Service error

Object Parameter of default response:

Name	Type	Description
error	string	Error message
status	"100", "101", "200", "201", "202", "203", "204", "205", "206", "300", "301", "302", "303", "304", "305", "307", "400", "401", "402", "403", "404", "405", "406", "407", "408", "409", "410", "411", "412", "413", "414", "415", "416", "417", "500", "501", "502", "503", "504", "505"	Http status code

Example

local ret = Geo.getGroupItem({
  group = "device",
  id = "sn001"
})

if ret.error ~= nil then
  return ret.error
end

print(ret.value)
-- [expected return]
-- {
-- "status":200,
-- "value":{
--   "id":"sn001",
--   "item":{"temperature":23},
--   "coordinates":[90.4064,-55.1444]
-- }
-- }

getGroupItems

Get the items with the coordinates info through the given identities

Arguments

parameters (object) - Object containing service call parameters.

Name	Type	Description
group	string	Group name
idlist	[ string ]	List id of group items

Responses

Code	Body Type	Description
200	nil	Object of many id-keys each includes id, coordinates and item
default	object	Service error

Object Parameter of default response:

Name	Type	Description
error	string	Error message
status	"100", "101", "200", "201", "202", "203", "204", "205", "206", "300", "301", "302", "303", "304", "305", "307", "400", "401", "402", "403", "404", "405", "406", "407", "408", "409", "410", "411", "412", "413", "414", "415", "416", "417", "500", "501", "502", "503", "504", "505"	Http status code

Example

local ret = Geo.getGroupItems({
  group = "device",
  idlist = {
    "sn001",
    "sn008"
  }
})
if ret.error ~= nil then
  return ret.error
end
print(ret.value)
-- [expected return]
-- for id of which within a idlist not existing inside a group will not be returned.
-- {
-- "status":200,
-- "value":{
--   "sn002":{
--     "id":"sn002",
--     "coordinates":[100.4064,-55.1444],
--     "item":{"temperature":23}},
--   "sn001":{
--     "id":"sn001",
--     "coordinates":[90.4064,-55.1444],
--     "item":{"temperature":23}}
-- }
-- }

inside

Check if a target is inside the fence

Arguments

parameters (object) - Object containing service call parameters.

Name	Type	Description
id	string	Id of group item
fence	string	Fence name
group	string	Group name
coordinates	[ number ]	Coordinates

Responses

Code	Body Type	Description
200	nil	Inside or not
default	object	Service error

Object Parameter of default response:

Name	Type	Description
error	string	Error message
status	"100", "101", "200", "201", "202", "203", "204", "205", "206", "300", "301", "302", "303", "304", "305", "307", "400", "401", "402", "403", "404", "405", "406", "407", "408", "409", "410", "411", "412", "413", "414", "415", "416", "417", "500", "501", "502", "503", "504", "505"	Http status code

Example

Geo.setFence({
  polygon = {
    {
      1, 1
    },
    {
      2, 1
    },
    {
      2, 2
    },
    {
      1, 2
    }
  },
  fence = "hotzone",
})
Geo.setGroupItem({
  id = "sn001",
  group = "device",
  item = {
    temperature = 23
  },
  coordinates = {
    1.1,
    1.5
  }
})
local ret = Geo.inside({
  group = "device",
  id = "sn001",
  fence = "hotzone"
})
if ret.error ~= nil then
  return ret.error
end
print(ret.value)
-- [expected return]
-- true OR false

ipToGeo

Get the geo information by ip

Arguments

parameters (object) - Object containing service call parameters.

Name	Type	Description
ip	string	Ip

Responses

Code	Body Type	Description
200	nil	Include range, country, region, city, metro, zip and coordinates
default	object	Service error

Object Parameter of default response:

Name	Type	Description
error	string	Error message
status	"100", "101", "200", "201", "202", "203", "204", "205", "206", "300", "301", "302", "303", "304", "305", "307", "400", "401", "402", "403", "404", "405", "406", "407", "408", "409", "410", "411", "412", "413", "414", "415", "416", "417", "500", "501", "502", "503", "504", "505"	Http status code

Example

local ret = Geo.ipToGeo({
  ip = "222.133.89.199"
})
if ret.error ~= nil then
  return ret.error
end
print(ret.value)
-- [expected return]
-- {
-- "country":"CN",
-- "region":"25",
-- "coordinates":[116.9972,36.6683],
-- "city":"Jinan",
-- "range":[3733274624,3733303671],
-- "metro":0,
-- "zip":0
-- }

listFenceEvents

list all fence events through a given group item

Arguments

parameters (object) - Object containing service call parameters.

Name	Type	Description
id	string	Id of group item
group	string	Group name
limit	integer	Amount data of one page
match	string	Redis match string
cursor	integer	To fetch next page of result until meet 0

Responses

Code	Body Type	Description
200	nil	Include next cursor and fence info with condition
default	object	Service error

Object Parameter of default response:

Name	Type	Description
error	string	Error message
status	"100", "101", "200", "201", "202", "203", "204", "205", "206", "300", "301", "302", "303", "304", "305", "307", "400", "401", "402", "403", "404", "405", "406", "407", "408", "409", "410", "411", "412", "413", "414", "415", "416", "417", "500", "501", "502", "503", "504", "505"	Http status code

Example

Geo.setFence({
  fence = "region1",
  circle = {
    center = {
      120,
      20
    },
    distance = 1000000,
    unit = "km"
  }
})

Geo.addFenceEvent({
  group = "device",
  idlist = {
    "sn001"
  },
  fence = "region1",
  inside = true,
  duration = 5
})
print(Geo.listFenceEvents({
  id = "sn001",
  group = "device"
}))
-- [expected return]
-- {
-- "value":{
--   "cursor":0,
--   "fences":[
--   {
--   "fence":"region1",
--     "inside":true,
--     "circle":{
--       "center":[120,20],
--       "unit":"km",
--       "distance":1000000},
--     "duration":5}
--   ]
-- },
-- "status":200
-- }

listFences

list all fences

Arguments

parameters (object) - Object containing service call parameters.

Name	Type	Description
limit	integer	Amount data of one page
match	string	Redis match string
cursor	integer	To fetch next page of result until meet 0

Responses

Code	Body Type	Description
200	nil	Include next cursor and fence information
default	object	Service error

Object Parameter of default response:

Name	Type	Description
error	string	Error message
status	"100", "101", "200", "201", "202", "203", "204", "205", "206", "300", "301", "302", "303", "304", "305", "307", "400", "401", "402", "403", "404", "405", "406", "407", "408", "409", "410", "411", "412", "413", "414", "415", "416", "417", "500", "501", "502", "503", "504", "505"	Http status code

Example

local circle = Geo.setFence({
  fence = "myCircle",
  circle = {
    center = {
      120.1,
      20.2
    },
    distance = 100,
    unit = "km"
  }
})
local ret = Geo.listFences({
  match = "my"
})
if ret.error ~= nil then
  return ret.error
end
print(ret.value.fences)
-- [expected return]
-- [
-- {
-- "fence":"myCircle",
-- "circle":{
--   "unit":"km",
--   "distance":100,
--   "center":[120.1,20.2]}
-- },
-- {
-- "fence":"myPolygon",
-- "polygon":[[1,10],[1,2],[8,1],[2,2]]
-- }
-- ]

nearby

Search the items within the given center and radius

Arguments

parameters (object) - Object containing service call parameters.

Name	Type	Description
id	string	Id of group item
unit	"m", "km", "mi", "ft"	Unit Default: "m"
group	string	Group name
limit	integer	Amount data of one page
cursor	object	Set for cache and not to return response
cursor.key	string	Id of the cache after nearby
cursor.expired	number	Expired time
orderby	"asc", "desc"	Desc or asc
distance	number	Distance
coordinates	[ number ]	Coordinates

Responses

Code	Body Type	Description
200	nil	List of objects with id, coodinates and item information
default	object	Service error

Object Parameter of default response:

Name	Type	Description
error	string	Error message
status	"100", "101", "200", "201", "202", "203", "204", "205", "206", "300", "301", "302", "303", "304", "305", "307", "400", "401", "402", "403", "404", "405", "406", "407", "408", "409", "410", "411", "412", "413", "414", "415", "416", "417", "500", "501", "502", "503", "504", "505"	Http status code

Example

local ret = Geo.nearby({
  distance = 100,
  group = "device",
  limit = 10000,
  coordinates = {
    79.4137,
    -79.4137
  },
  orderby = "desc",
  unit = "m"
})
if ret.error ~= nil then
  return ret.error
end
print(ret.value)
-- [expected return]
-- [
-- {
--   "id":"sn002",
--   "coordinates":[100.4064,-55.1444],
--   "item":{"temperature":23}
-- },
-- {
--    "id":"sn001",
--    "coordinates":[90.4064,-55.1444],
--    "item":{"temperature":23}
-- }
-- ]

removeAll

remove all data stored in Geo service

Arguments

parameters (object) - Object containing service call parameters.

Name	Type	Description
confirmed	string	Protective parameter to avoid mistake

Responses

Code	Body Type	Description
204	nil	Ok
default	object	Service error

Object Parameter of default response:

Name	Type	Description
error	string	Error message
status	"100", "101", "200", "201", "202", "203", "204", "205", "206", "300", "301", "302", "303", "304", "305", "307", "400", "401", "402", "403", "404", "405", "406", "407", "408", "409", "410", "411", "412", "413", "414", "415", "416", "417", "500", "501", "502", "503", "504", "505"	Http status code

Example

local ret = Geo.removeAll({
  confirmed = '1a3af55fty'
})
if ret.error ~= nil then
  return ret.error
end
return 'ok'

removeFence

Remove specific the fence

Arguments

parameters (object) - Object containing service call parameters.

Name	Type	Description
fence	string	Fence name

Responses

Code	Body Type	Description
204	nil	Ok
default	object	Service error

Object Parameter of default response:

Name	Type	Description
error	string	Error message
status	"100", "101", "200", "201", "202", "203", "204", "205", "206", "300", "301", "302", "303", "304", "305", "307", "400", "401", "402", "403", "404", "405", "406", "407", "408", "409", "410", "411", "412", "413", "414", "415", "416", "417", "500", "501", "502", "503", "504", "505"	Http status code

Example

local ret = Geo.removeFence({
  fence = "hotzone",
})
if ret.error ~= nil then
  return ret.error
end
return "ok"

removeFenceEvent

Remove a fence event

Arguments

parameters (object) - Object containing service call parameters.

Name	Type	Description
fence	string	Fence name
group	string	Group name
idlist	[ string ]	List id of group items

Responses

Code	Body Type	Description
204	nil	Ok
default	object	Service error

Object Parameter of default response:

Name	Type	Description
error	string	Error message
status	"100", "101", "200", "201", "202", "203", "204", "205", "206", "300", "301", "302", "303", "304", "305", "307", "400", "401", "402", "403", "404", "405", "406", "407", "408", "409", "410", "411", "412", "413", "414", "415", "416", "417", "500", "501", "502", "503", "504", "505"	Http status code

Example

local ret = Geo.removeFenceEvent({
  group = "device",
  idlist = {
    "sn001",
    "sn002"
  },
  fence = "myPolygon"
})

removeGroup

Remove the group includes all items in this group

Arguments

parameters (object) - Object containing service call parameters.

Name	Type	Description
group	string	Group name

Responses

Code	Body Type	Description
204	nil	Ok
default	object	Service error

Object Parameter of default response:

Name	Type	Description
error	string	Error message
status	"100", "101", "200", "201", "202", "203", "204", "205", "206", "300", "301", "302", "303", "304", "305", "307", "400", "401", "402", "403", "404", "405", "406", "407", "408", "409", "410", "411", "412", "413", "414", "415", "416", "417", "500", "501", "502", "503", "504", "505"	Http status code

Example

local ret = Geo.removeGroup({
  group = "device",
})
if ret.error ~= nil then
  return ret.error
end
return "ok"

removeGroupItem

Remove the item from a group

Arguments

parameters (object) - Object containing service call parameters.

Name	Type	Description
id	string	Id of group item
group	string	Group name

Responses

Code	Body Type	Description
204	nil	Ok
default	object	Service error

Object Parameter of default response:

Name	Type	Description
error	string	Error message
status	"100", "101", "200", "201", "202", "203", "204", "205", "206", "300", "301", "302", "303", "304", "305", "307", "400", "401", "402", "403", "404", "405", "406", "407", "408", "409", "410", "411", "412", "413", "414", "415", "416", "417", "500", "501", "502", "503", "504", "505"	Http status code

Example

local ret = Geo.removeGroupItem({
  group = "device",
  id = "sn0001"
})
if ret.error ~= nil then
  return ret.error
end
return "ok"

removeNearbyCursor

Remove the cursor of the result from a nearby operation

Arguments

parameters (object) - Object containing service call parameters.

Name	Type	Description
key	string	Id of the cache after nearby

Responses

Code	Body Type	Description
204	nil	Ok
default	object	Service error

Object Parameter of default response:

Name	Type	Description
error	string	Error message
status	"100", "101", "200", "201", "202", "203", "204", "205", "206", "300", "301", "302", "303", "304", "305", "307", "400", "401", "402", "403", "404", "405", "406", "407", "408", "409", "410", "411", "412", "413", "414", "415", "416", "417", "500", "501", "502", "503", "504", "505"	Http status code

Example

Geo.removeNearbyCursor({
  key = websocket_info.socket_id
})

setFence

Set the fence with the polygon or circle

Arguments

parameters (object) - Object containing service call parameters.

Name	Type	Description
fence	string	Fence name
circle	object	Parameters
circle.unit	"m", "km", "mi", "ft"	Unit Default: "m"
circle.center	[ number ]	Coordinates
circle.distance	number	Distance
polygon	[ [ number ] {2..2} ] {3..}	Polygon shape

Responses

Code	Body Type	Description
204	nil	Ok
default	object	Service error

Object Parameter of default response:

Name	Type	Description
error	string	Error message
status	"100", "101", "200", "201", "202", "203", "204", "205", "206", "300", "301", "302", "303", "304", "305", "307", "400", "401", "402", "403", "404", "405", "406", "407", "408", "409", "410", "411", "412", "413", "414", "415", "416", "417", "500", "501", "502", "503", "504", "505"	Http status code

Example

local polygon = Geo.setFence({
  fence = "myPolygon",
  polygon = {
    {
      1, 10
    },
    {
      1, 2
    },
    {
      8, 1
    },
    {
      2, 2
    }
  }
})
local circle = Geo.setFence({
  fence = "myCircle",
  circle = {
    center = {
      120.1,
      20.2
    },
    distance = 100,
    unit = "km"
  }
})
return "ok"

setGroupItem

Set a item with the coordinates in the group.

Arguments

parameters (object) - Object containing service call parameters.

Name	Type	Description
id	string	Id of group item
item	object	Properties of the item
group	string	Group name
coordinates	[ number ]	Coordinates

Responses

Code	Body Type	Description
204	nil	Ok
default	object	Service error

Object Parameter of default response:

Name	Type	Description
error	string	Error message
status	"100", "101", "200", "201", "202", "203", "204", "205", "206", "300", "301", "302", "303", "304", "305", "307", "400", "401", "402", "403", "404", "405", "406", "407", "408", "409", "410", "411", "412", "413", "414", "415", "416", "417", "500", "501", "502", "503", "504", "505"	Http status code

Example

local ret = Geo.setGroupItem({
  group = "device",
  id = "sn001",
  item = {
    temperature = 23
  },
  coordinates = {
    90.4064,
    -55.1444
  }
})
if ret.error ~= nil then
  return ret.error
end
return "ok"

---

Events

fence

An event message containing group, id, item, fence ...

Arguments

data (object) - Parameters

Name	Type	Description
id	string	Id of group item
item	object	Properties of the item
fence	string	Fence name
group	string	Group name
inside	boolean	Inside of the fence or not
duration	integer	Duration of the fence detection Minimum: 1
coordinates	[ number ]	Coordinates

Example

function handle_geo_fence (data)

 -- Your logic comes here 

end

Service Health Check

Operations

/health

Enable the hosting system to check if service is active and running

Arguments

No Content

Responses

Name	Type	Description
200	string	OK

Errors

No content