This document describes the API designed to integrate Proximity Kit with other systems. It is specifically intended to manage creation and deletion of kits, regions, the associated meta data.
Data synchronization, communicating with the SDKs, configuring hardware is not part of the Admin API. Radius Networks has other resources for many of those needs.
This API uses IDs for linkage, which makes it possible to cache documents from compound responses and then limit subsequent requests to only the documents that aren't already present locally.
Resource relationships are created through the use of URI templates and resource identifiers. To prevent future breakage we recommend creating the URIs from the templates over hardcoding to the individual resources.
The API Key is passed via the Authorization header:
Authorization: Token token="secret"
The API Key is associated with your account and has access to all the resources associated with your account. Account-specific API keys have different permissions than the web login users that can interact with the dashboard, and the access may be different.
Example:
curl -H 'Authorization: Token token="sandbox"' "https://proximitykit.radiusnetworks.com/api/v1.json"
API Tokens can be managed in your Radius Networks Account Profile.
Note: Per RFC 2616 the Authorization Header's token needs to be surrounded by double quotes ("
).
The content type is vnd+json
, and should be set in the Content-Type header:
Content-Type: application/vnd.api+json
GET /api/v1
The list of links for the resources available to your account.
Root Document:
GET /api/v1
{
"version": "1.0",
"links": {
"users.kits": "https://proximitykit.radiusnetworks.com/api/v1/kits/{users.kits}"
},
"users": [
{
"id": 3,
"links": {
"kits": [52,53]
}
}
]
}
Key | Value |
---|---|
version |
The media type version |
links[users.kits] |
The url template for a kit resource |
users[links][kits] |
List of kit IDs that belong to a user |
Curl Example:
% curl -s \
-X GET \
-H 'Authorization: Token token="secret"' \
-H "Content-Type: application/vnd.api+json" \
https://proximitykit.radiusnetworks.com/api/v1
GET /api/v1/kits/:id
Return the kit resource, describing the attributes and related beacons.
{
"version": "1.0",
"links": {
"kits.beacons": "https://proximitykit.radiusnetworks.com/api/v1/beacons/{kits.beacons}",
"kits.circle_overlays": "https://proximitykit.radiusnetworks.com/api/v1/circle_overlays/{kits.circle_overlays}"
},
"kits": [
{
"name": "Ancient Rome",
"id": 52,
"links": {
"beacons": [2,3,4,5],
"circle_overlays": [3,4,5,6]
}
}
]
}
Key | Value |
---|---|
version |
The media type version |
links[kits.beacons] |
The url template for an beacon resource |
links[kits.circle_overlays] |
The url template for a geofence circle overlay resource |
kits[links][beacons] |
List of kit IDs that belong to a user |
Curl Example:
% curl -s \
-X GET \
-H 'Authorization: Token token="secret"' \
-H "Content-Type: application/vnd.api+json" \
https://proximitykit.radiusnetworks.com/api/v1/kits/52
GET /api/v1/kits/:id
Return a paginated of kit resources.
{
"version": "1.0",
"meta": {
"current": "https://proximitykit.radiusnetworks.com/api/v1/kits?page=3",
"next": "https://proximitykit.radiusnetworks.com/api/v1/kits?page=4",
"previous": "https://proximitykit.radiusnetworks.com/api/v1/kits?page=2",
"first": "https://proximitykit.radiusnetworks.com/api/v1/kits?page=1",
"last": "https://proximitykit.radiusnetworks.com/api/v1/kits?page=10"
},
"links": {
"kits.beacons": "https://proximitykit.radiusnetworks.com/api/v1/beacons/{kits.beacons}"
},
"kits": [
{
"name": "Ancient Rome",
"id": 52,
"links": {
"beacons": [ 2, 3, 4, 5 ]
}
},
//...
]
}
Key | Value |
---|---|
version |
The media type version |
links[kits.beacons] |
The url template for an beacon resource |
kits[links][beacons] |
List of kit IDs that belong to a user |
meta[next] |
URI of the next page of results |
meta[previous] |
URI of the previous page of results |
meta[first] |
URI of the first page of results |
meta[last] |
URI of the last page of results |
To create a kit make a post request to the /api/v1/kits
POST /api/v1/kits
The response will include the JSON representation of the newly created kit as well as a Location
header with the URI of the resource.
Example:
{"kits": [{ "name": "My New Name" }] }
Required Parameters:
Parameter | Description |
---|---|
name | The name of the kit |
Curl Example:
% curl -sv \
-X POST \
-H 'Authorization: Token token="secret"' \
-H "Content-Type: application/vnd.api+json" \
-d ' {"kits":[{ "name": "My Name" }]}'
https://proximitykit.radiusnetworks.com/api/v1/kits
< HTTP/1.1 201 Created
< Location: https://proximitykit.radiusnetworks.com/kits/56
< Content-Type: application/vnd.api+json; charset=utf-8
{
"kits": [
{
"name": "My Name",
"id": 56,
"links": { "beacons": [] }
}
]
}
To update a kit make a put request to the /api/v1/kits
.
PUT /api/v1/kit/:id
Example:
{"kits": [{ "name": "My New Name" }] }
Parameters:
Parameter | Description |
---|---|
name |
The name of the kit |
Curl Example:
% curl -sv \
-X PUT \
-H 'Authorization: Token token="secret"' \
-H "Content-Type: application/vnd.api+json" \
-d ' {"kits":[{ "name": "Silly Name" }]}' \
https://proximitykit.radiusnetworks.com/api/v1/kits/56
< HTTP/1.1 204 No Content
To delete a kit make a delete request to the individual kit url.
DELETE /api/v1/kit/:id
The response be 201 No Content
if the delete was successful.
Curl Example:
% curl -sv \
-X DELETE \
-H 'Authorization: Token token="secret"' \
-H "Content-Type: application/vnd.api+json"
https://proximitykit.radiusnetworks.com/api/v1/kits/56
< HTTP/1.1 204 No Content
GET /api/v1/beacons/:id
This will return an beacon resource.
{
"links": {
"beacons.attributes": "https://proximitykit.radiusnetworks.com/api/v1/beacon_attributes/{beacons.attributes}"
},
"beacons": [
{
"id": 6,
"name": "Earth",
"uuid": "E58171D9-8398-4453-A991-5593682DDB56",
"major": 1000,
"minor": 1,
"links": {
"attributes": [3,4]
}
}
]
}
Key | Value |
---|---|
version |
The media type version |
links[beacons.attributes] |
The url template for a beacon attribute resource |
beacons[name] |
Display name for the beacon |
beacons[uuid] |
Orgnization level proximity identifier |
beacons[major] |
Group level proximity identifier |
beacons[minor] |
Physical beacon proximity identifier |
beacons[links][attributes] |
List of attribute IDs that belong to the beacon |
Curl Example:
% curl -s \
-X GET \
-H 'Authorization: Token token="secret"' \
-H "Content-Type: application/vnd.api+json" \
https://proximitykit.radiusnetworks.com/api/v1/beacons/6
To create a beacon make a POST request to the /api/v1/beacons
Parameters
Parameter | Description | |
---|---|---|
kit_id |
The ID of the associated kit | Required |
uuid |
The beacon UUID | Required |
name |
The name of the beacon | |
major |
The major beacon identifier | |
minor |
The minor beacon identifier |
POST /api/v1/beacons
The response will include the JSON representation of the newly created kit as well as a Location
header with the URI of the resource.
Example:
{
"links": {
"beacons.attributes": "https://proximitykit.radiusnetworks.com/api/v1/beacon_attributes/{beacons.attributes}"
},
"beacons": [
{
"id": 6,
"name": "Earth",
"uuid": "E58171D9-8398-4453-A991-5593682DDB56",
"major": 1000,
"minor": 1,
"links": {
"attributes": []
}
}
]
}
Curl Example:
% curl -sv \
-X POST \
-H 'Authorization: Token token="secret"' \
-H "Content-Type: application/vnd.api+json" \
-d '{"beacons": [{"kit_id":52, "name": "Earth 2", "uuid": "E58171D9-8398-4453-A991-5593682DDB56", "major": 1002, "minor": 1}]}' \
https://proximitykit.radiusnetworks.com/api/v1/beacons
< HTTP/1.1 201 Created
< Location: https://proximitykit.radiusnetworks.com/api/v1/beacons/7
To update a beacon make a put request /api/v1/beacons/:id
Parameters
Parameter | Description | |
---|---|---|
kit_id |
The ID of the associated kit | Required |
uuid |
The beacon UUID | |
name |
The name of the beacon | |
major |
The major beacon identifier | |
minor |
The minor beacon identifier |
PUT /api/v1/beacon/{beacon_id}
Example:
{
"beacons": [
{
"kit_id": 1,
"name": "My New Name",
"uuid": "d16eae19-6fce-4198-a5a5-469c9599b709",
"major": 1,
"minor": 1
}
]
}
To delete a beacon make a delete request to api/v1/beacon/:id
.
DELETE /api/v1/beacon/:id
Curl Example:
% curl -sv \
-X DELETE \
-H 'Authorization: Token token="secret"' \
-H "Content-Type: application/vnd.api+json" \
https://proximitykit.radiusnetworks.com/api/v1/beacons/7
< HTTP/1.1 204 No Content
GET /api/v1/beacon_attributes/:id
This will return a list of beacon attributes.
{
"beacon_attributes": [
{
"id": 4,
"key": "population",
"value": "eleventy billion"
}
]
}
Curl Example:
% curl -s \
-X GET \
-H 'Authorization: Token token="secret"' \
-H "Content-Type: application/vnd.api+json" \
https://proximitykit.radiusnetworks.com/api/v1/beacon_attributes/4
To create an attribute make a post request to api/v1/beacon_attributes
Parameters
Parameter | Description | |
---|---|---|
beacon_id |
The ID of the associated beacon | Required |
key |
The key value | |
value |
The data associated with the key |
POST /api/v1/beacon_attributes
Example:
{
"beacon_attributes": [
{
"beacon_id": 5,
"key": "venue",
"value": "spaceship"
}
]
}
% curl -sv \
-X POST \
-H 'Authorization: Token token="secret"' \
-H "Content-Type: application/vnd.api+json" \
-d '{ "beacon_attributes": [ { "beacon_id": 5, "key": "venue", "value": "spaceship" } ]}' \
https://proximitykit.radiusnetworks.com/api/v1/beacon_attributes
< HTTP/1.1 201 Created
< Location: https://proximitykit.radiusnetworks.com/api/v1/beacon_attributes/5.5
To update an attribute make a post request to api/v1/beacon_attributes/:id
.
Parameters
Parameter | Description | |
---|---|---|
key |
The key value | Required |
value |
The data associated with the key | Required |
beacon_id |
The ID of the parent beacon |
PUT /api/v1/beacon_attributes/:id
Example:
{
"beacon_attributes": [
{
"key": "venue",
"value": "spaceship with dinosaurs"
}
]
}
Curl Example:
% curl -sv \
-X PUT \
-H 'Authorization: Token token="secret"' \
-H "Content-Type: application/vnd.api+json" \
-d '{ "beacon_attributes": [ { "key": "venue", "value": "spaceship with dinosaurs" } ]}' \
https://proximitykit.radiusnetworks.com/api/v1/beacon_attributes/5
< HTTP/1.1 204 No Content
To delete an attribute make a delete request to the individual beacon_attribute_url
.
DELETE /api/v1/beacon_attributes/:id
Curl Example:
% curl -sv \
-X DELETE \
-H 'Authorization: Token token="secret"' \
-H "Content-Type: application/vnd.api+json" \
https://proximitykit.radiusnetworks.com/api/v1/beacon_attributes/4
< HTTP/1.1 204 No Content
GET /api/v1/circle_overlays/:id
This will return a circle overlay resource.
{
"circle_overlays" : [
{
"id" : 7,
"name" : "Headquarters",
"radius" : 80.704567,
"links" : {
"kit" : 4,
"attributes" : [],
"self" : "https://proximitykit.radiusnetworks.com/api/v1/circle_overlays/760"
},
"center_longitude" : -77.066093,
"center_latitude" : 38.904539
}
],
"links" : {
"circle_overlays.kit" : "https://proximitykit.radiusnetworks.com/api/v1/kits/{circle_overlays.kit}",
"circle_overlays.attributes" : "https://proximitykit.radiusnetworks.com/api/v1/circle_overlay_attributes/{circle_overlays.attributes}"
}
}
Key | Value |
---|---|
version |
The media type version |
links[circle_overlays.attributes] |
The url template for a circle overlay attribute resource |
circle_overlays[name] |
Display name for the circle overlay |
circle_overlays[radius] |
Radius of the geofence in meters |
circle_overlays[center_longitude] |
longitude of the center point |
circle_overlays[center_latitude] |
latitude of the center point |
circle_overlays[links][attributes] |
List of attribute IDs that belong to the circle overlay |
Curl Example:
% curl -s \
-X GET \
-H 'Authorization: Token token="secret"' \
-H "Content-Type: application/vnd.api+json" \
https://proximitykit.radiusnetworks.com/api/v1/circle_overlays/6
To create a circle overlay make a POST request to the /api/v1/circle_overlays
Parameters
Parameter | Description | |
---|---|---|
kit_id |
The ID of the associated kit | Required |
name |
Display name for the circle overlay | |
radius |
Radius of the geofence in meters | required |
center_longitude |
longitude of the center point | required |
center_latitude |
latitude of the center point | required |
POST /api/v1/circle_overlays
The response will include the JSON representation of the newly created kit as well as a Location
header with the URI of the resource.
Example:
{
"circle_overlays": [
{
"kit_id": 6,
"name" : "Headquarters",
"radius" : 80.704567,
"center_longitude" : -77.066093,
"center_latitude" : 38.904539
}
]
}
Curl Example:
% curl -sv \
-X POST \
-H 'Authorization: Token token="secret"' \
-H "Content-Type: application/vnd.api+json" \
-d '{"circle_overlays": [{"kit_id":52, "name" : "Headquarters", "radius" : 80.704567, "center_longitude" : -77.066093, "center_latitude" : 38.904539 }]}' \
https://proximitykit.radiusnetworks.com/api/v1/circle_overlays
< HTTP/1.1 201 Created
< Location: https://proximitykit.radiusnetworks.com/api/v1/circle_overlays/7
To update a circle overlay make a put request /api/v1/circle_overlays/:id
Parameters
Parameter | Description | |
---|---|---|
kit_id |
The ID of the associated kit | Required |
name |
Display name for the circle overlay | |
radius |
Radius of the geofence in meters | required |
center_longitude |
longitude of the center point | required |
center_latitude |
latitude of the center point | required |
PUT /api/v1/circle_overlay/{circle_overlay_id}
Example:
{
"circle_overlays": [
{
"kit_id": 1,
"name" : "Headquarters",
"radius" : 80.704567,
"center_longitude" : -77.066093,
"center_latitude" : 38.904539
}
]
}
To delete a circle overlay make a delete request to api/v1/circle_overlays/:id
.
DELETE /api/v1/circle_overlays/:id
Curl Example:
% curl -sv \
-X DELETE \
-H 'Authorization: Token token="secret"' \
-H "Content-Type: application/vnd.api+json" \
https://proximitykit.radiusnetworks.com/api/v1/circle_overlays/7
< HTTP/1.1 204 No Content
GET /api/v1/circle_overlay_attributes/:id
This will return a list of circle overlay attributes.
{
"circle_overlay_attributes": [
{
"id": 4,
"key": "population",
"value": "eleventy billion"
}
]
}
Curl Example:
% curl -s \
-X GET \
-H 'Authorization: Token token="secret"' \
-H "Content-Type: application/vnd.api+json" \
https://proximitykit.radiusnetworks.com/api/v1/circle_overlay_attributes/4
To create an attribute make a post request to api/v1/circle_overlay_attributes
Parameters
Parameter | Description | |
---|---|---|
circle_overlay_id |
The ID of the associated circle overlay | Required |
key |
The key value | |
value |
The data associated with the key |
POST /api/v1/circle_overlay_attributes
Example:
{
"circle_overlay_attributes": [
{
"circle_overlay_id": 5,
"key": "venue",
"value": "spaceship"
}
]
}
% curl -sv \
-X POST \
-H 'Authorization: Token token="secret"' \
-H "Content-Type: application/vnd.api+json" \
-d '{ "circle_overlay_attributes": [ { "circle_overlay_id": 5, "key": "venue", "value": "spaceship" } ]}' \
https://proximitykit.radiusnetworks.com/api/v1/circle_overlay_attributes
< HTTP/1.1 201 Created
< Location: https://proximitykit.radiusnetworks.com/api/v1/circle_overlay_attributes/5.5
To update an attribute make a post request to api/v1/circle_overlay_attributes/:id
.
Parameters
Parameter | Description | |
---|---|---|
key |
The key value | Required |
value |
The data associated with the key | Required |
circle_overlay_id |
The ID of the parent circle overlay |
PUT /api/v1/circle_overlay_attributes/:id
Example:
{
"circle_overlay_attributes": [
{
"key": "venue",
"value": "swimming pool room"
}
]
}
Curl Example:
% curl -sv \
-X PUT \
-H 'Authorization: Token token="secret"' \
-H "Content-Type: application/vnd.api+json" \
-d '{ "circle_overlay_attributes": [ { "key": "venue", "value": "swiming pool room" } ]}' \
https://proximitykit.radiusnetworks.com/api/v1/circle_overlay_attributes/5
< HTTP/1.1 204 No Content
To delete an attribute make a delete request to the individual circle_overlay_attribute_url
.
DELETE /api/v1/circle_overlay_attributes/:id
Curl Example:
% curl -sv \
-X DELETE \
-H 'Authorization: Token token="secret"' \
-H "Content-Type: application/vnd.api+json" \
https://proximitykit.radiusnetworks.com/api/v1/circle_overlay_attributes/4
< HTTP/1.1 204 No Content