Introduction

BeaconsInSpace provides APIs for you to easily build and monetize your context-aware apps with beacons. Think of us as the infrastructure layer for micro-location; we provide your apps with instant access to beacons and structured beacon data at scale.

The purpose of this introduction is to provide you with an overview of BeaconsInSpace and the features and services we provide.

We focus on three major features:

  • Accessing beacons
  • Querying beacon place data
  • Sending location data for analytics and monetization

We have two core services that are organized around our major features:

  • BeaconsInSpace REST API: our core API that enables our three major features; accessing beacon infrastructure, querying structured place data, and sending location data for analytics and monetization.
  • Mission Control: our cloud dashboard for you to access your API key, input test beacons, view user analytics, and integrate with third-party platforms and APIs.

    The cloud dashboard and the API work in tandem. You can access Mission Control, your API Key, and input some test beacons for free when you sign up.
logo

REST API Overview

The BeaconsInSpace REST API is our core API for interacting with our beacon network and for sending us location-based event data.

The API allows you to:
Access identifiers of beacons
Query structured place data about individual beacons
Sending location data for analytics and monetization with Events

Authentication

To use the BeaconsInSpace API you need to use HTTP Basic Auth.

Basic Auth base64 encodes a 'username:password' with 'Basic ' prepended.

The Basic Auth username should be your API key and your password should be your apps bundleId (iOS) or PackageName (Android). Your API key can be found in the Account section of Mission Control.

For example, if your username (API Key) is '54d691399025447954208154d691399025f539132065' and the password is 'com.beaconsinspace.jetfuel' the final result should be passed in the authorization header like the following:

Basic Authorization Header
'Authorization: Basic NTRkNjkxMzk5MDI1NDQ3OTU0MjA4MTU0ZDY5MTM5OTAyNWY1MzkxMzIwNjU6Y29tLmJlYWNvbmluc3BhY2UuamV0ZnVlbA=='

Base URL

All API URLs referenced in this documentation begin with the following base:

https://api.beaconsinspace.com/v1
    

Data Structure

The BeaconsInSpace REST API returns JSON for all calls. Here is an example of an API Request.

{
  "code":200,
  "message":"Success",
  "data": {
    some:data
  }
}
    

Code: 
Integer

The code defines the status of the request. 200 means success, anything other than 200 means there was a problem with the request.

Message:
String

The message provides information about the request results.

Data:
Array | Object | Null

The data that is returned by the request.

Response Codes

The BeaconsInSpace REST API returns response codes under these conditions:

Code
Name
Description

200

Success

The request was successful.

301

Redirect

You are being redirected to another location to fulfill the request.

400

Bad Request

One or more of the required arguments was non-existent or invalid. The message body will contain more information.

401

Unauthorized

Authentication failed for user credentials or access tokens.

403

Access Denied

User does not have access to requested information.

404

Not Found

Information user desires was not found.

409

Conflict

The arguments conflict with each other, even though the arguments are valid.

429

Too many failed requests. Rate limit reached

This can happen due to too many failed requests in a specific amount of time.

500

Internal Server Error

The server encountered a problem retrieving the information.

501

Incomplete

The logic to retrieve the information requested has not been implemented yet.

logo

iBeacon Endpoints

GET
Beacons
This route will return an array of beacon UUIDs for beacons you are subscribed to. There is a limit of 20 UUIDs returned.
Best Practice: You should make a GET Beacons request at least once per day. This is because beacon UUIDs change at random intervals for security purposes.
https://api.beaconsinspace.com/v1/beacon
    
Example
Try this in your terminal, and be sure you have successfully implemented Basic Auth:
curl \
-H "Authorization: Basic NTRkNjkxMzk5MDI1NDQ3OTU0MjA4MTU0ZDY5MTM5OTAyNWY1MzkxMzIwNjU6Y29tLmJlYWNvbmluc3BhY2UuamV0ZnVlbA==" \
'https://api.beaconsinspace.com/v1/beacon'
    
Result Format
{
    "code": 200,
    "message": "Success",
    "data": [
        {
            "protocol": "ibeacon",
            "uuid": "99259a46-a024-11e5-8994-feff819cdc9f"
        }
    ]
}
    
GET
Beacon place details
This route will return detailed place information on an individual beacon. You can create some cool things by plugging this data into other APIs.
Best Practice: Call this route immediately after ranging for a beacons UUID, Major, and Minor. This is especially important when ranging in the background, where by default you only have 10 seconds to take an action after a beacon region is entered.
https://api.beaconsinspace.com/v1/beacon?uuid=:uuid&major=:major&minor=:minor
    
Parameters
*required
Name
Type
Description
*

uuid

String

A 16 byte standard identifier for the iBeacon

*

major

Integer

A 2 byte sub-identifier for the iBeacon

*

minor

Integer

A 2 byte sub-identifier for the iBeacon

*

createdAt

Double

Please pass a UNIX UTC Timestamp. Be as accurate as possible, values to the 6th decimal place are preferred. e.g. 1458854814.466618

Example
Try this in your terminal, and be sure you have successfully implemented Basic Auth:
curl \
-H "Authorization: Basic NTRkNjkxMzk5MDI1NDQ3OTU0MjA4MTU0ZDY5MTM5OTAyNWY1MzkxMzIwNjU6Y29tLmJlYWNvbmluc3BhY2UuamV0ZnVlbA==" \
'https://api.beaconsinspace.com/v1/beacon?uuid=99259a46-a024-11e5-8994-feff819cdc9f&major=2434&minor=2&createdAt=1458854814.466618'
    
Result Format
{
    "code": 200,
    "message": "Success",
    "data": {
        "beaconId": "beaconjR",
        "protocol": "ibeacon",
        "establishment": "Foley's Tavern",
        "establishmentType": "restaurant",
        "touchpoint": "Bar",
        "touchpointType": [],
        "verticalPosition": "1st Floor",
        "street": "100 Foghladha Street",
        "city": "Boston",
        "state": "Massachusetts",
        "zip": "02111",
        "country": "USA",
        "timezone": "America/New_York",
        "latitude": 42.3514653,
        "longitude": -71.0601767
    }
}
    
GET
Nearest beacons
This will return a maximum of 20 beacon identifiers nearest to the latitude and longitude provided. The identifiers will be returned in ascending order; the nearest identifiers will be returned first.
Best Practice: Use this route to address the 20 region limit in iOS, by refreshing the beacon regions (UUIDs) you are monitoring for when a user changes location. Because we provide latitude and longitude fields in every Beacon place details request, you can find the nearest beacons every time your user enters a beacon region. This means you don't need GPS functionality in your app to return the nearest beacons.
https://api.beaconsinspace.com/v1/beacon?latitude=:latitude&longitude=:longitude
    
Parameters
*required
Name
Type
Description
*

latitude

Double

The latitude of the user of your app

*

longitude

Double

The longitude of the user of your app

Example
Try this in your terminal, and be sure you have successfully implemented Basic Auth:
curl \
-H "Authorization: Basic NTRkNjkxMzk5MDI1NDQ3OTU0MjA4MTU0ZDY5MTM5OTAyNWY1MzkxMzIwNjU6Y29tLmJlYWNvbmluc3BhY2UuamV0ZnVlbA==" \
'https://api.beaconsinspace.com/v1/beacon?latitude=42.3514650&longitude=-71.0601770'
    
Result Format
{
    "code": 200,
    "message": "Success",
    "data": [
        {
            "protocol": "ibeacon",
            "uuid": "99259a46-a024-11e5-8994-feff819cdc9f"
        }
    ]
}
    
GET
Nearest beacon place details
You can request beacon place details based on latitude and longitude. This will return a maximum of 20 place details. The results will be returned in ascending order; the nearest place details will be returned first.
https://api.beaconsinspace.com/v1/beacon?latitude=:latitude&longitude=:longitude&placeDetails=:placeDetails&limit=:limit
    
Parameters
*required
Name
Type
Description
*

latitude

Double

The latitude of the user of your app

*

longitude

Double

The longitude of the user of your app

*

placeDetails

Integer

You must enter value "1" to return beacon place details

limit

Integer

The number of Beacon place details to return. Defaults to 20. Max is 20

Example
Try this in your terminal, and be sure you have successfully implemented Basic Auth:
curl \
-H "Authorization: Basic NTRkNjkxMzk5MDI1NDQ3OTU0MjA4MTU0ZDY5MTM5OTAyNWY1MzkxMzIwNjU6Y29tLmJlYWNvbmluc3BhY2UuamV0ZnVlbA==" \
'https://api.beaconsinspace.com/v1/beacon?latitude=42.3514650&longitude=-71.0601770&placeDetails=1'
    
Result Format
{
    "code": 200,
    "message": "Success",
    "data": [
        {
            "beaconId": "beaconjR",
            "protocol": "ibeacon",
            "establishment": "Foley's Tavern",
            "establishmentType": "restaurant",
            "touchpoint": "Bar",
            "touchpointType": [],
            "verticalPosition": "1st Floor",
            "street": "100 Foghladha Street",
            "city": "Boston",
            "state": "Massachusetts",
            "zip": "02111",
            "country": "USA",
            "timezone": "America/New_York",
            "latitude": 42.3514653,
            "longitude": -71.0601767,
            "distance": "0"
        }
    ]
}
    
POST
Event
In order to generate events associated with beacons, you should POST every time a user of your app enters and exits a beacon region regardless of whether the beacon was used by your app at that time or not.  

You can also use events to send GPS coordinates. We refer to enters and exits of beacon regions and coordinates passed from GPS as events. To learn more about sending GPS Events checkout our example.

Making a POST Event benefits you in three important ways:
  1. Analytics
    We generate your analytics from events. You cannot get analytics without events.
  2. Integrations
    All integrations with third-party platforms and APIs depend on events. You cannot use integrations without events.
  3. Monetization
    When you send us events we can monetize the location data for you from our brand partners. You cannot monetize without events.
Note: In order for us to provide you with the three points above, every POST should contain a unique user Id (userId2) and a unique user Id type (userIdType2).

For simplicity, we ask that you adhere to the guidelines below when providing a userId2 in any call:

iOS Policy: For userId2 you should always pass the IDFA (advertisingIdentifier).

Android Policy: For userId2 you should pass the AAID (Google's advertising ID).
https://api.beaconsinspace.com/v1/event
    
Parameters
*required
Name
Type
Description
*

userId2

String

An identifier that is unique to every user of your app.

*

userIdType2

String

The type of userId2. Accepted values are "IDFA", "AAID", or "WINID" (Windows Id)

*

detect

String

Either "gps" if you are passing a gps coordinate OR "enter" or "exit"  if you've entered or exited the proximity of a beacon respectively

*

createdAt

Double

Please pass a UNIX UTC Timestamp. Be as accurate as possible, values to the 6th decimal place are preferred. e.g. 1458854814.466618

ipAddress

String

The IP Address of the users device at the time the event occured

country

String

The country code of the users device. Needs to be 2 characters in ISO 3166-1 alpha 2 format (e.g. US, FR)

os

String

The operating system version of the users device

device

String

The model of the users device (e.g. iPhone 6)

language

String

The language of the users device. Needs to be 2 characters in "ISO 639-1" format (e.g. en, fr)

tz

String

The timezone of the users device

uuid

String

A 16 byte standard identifier for the iBeacon

major

Integer

A 2 byte sub-identifier for the iBeacon

minor

Integer

A 2 byte sub-identifier for the iBeacon

gpsLatitude

String

The latitude coordinates of the users device

gpsLongitude

String

The longitude coordinates of the users device

gpsHorizontalAccuracy

Double

The accuracy of the latitude and longitude, measured in meters

gpsAltitude

Double

The altitude of the device, measured in meters

gpsVerticalAccuracy

Double

The accuracy of the altitude, measured in meters

gpsSpeed

Double

The instantaneous speed of the device in meters per second

gpsFloor

Integer

The logical floor of the building in which the user is located

gpsCourse

Double

The direction in which the device is traveling

gpsBearing

Double

The bearing, in degrees

uid

String

A 16 byte identifier for the Eddystone consisting of namespaceId + instanceId.

rssi

JSON Array

RSSI values are passed as a JSON formatted array of objects with two properties in each object- “r” which represents the RSSI value and “t” which represents the Unix UTC Timestamp that the RSSI reading occurred. For example, [{"r":-92,"t":1448299902.548165}]

beaconId1

String

A 16 byte standard identifier for the beacon (e.g. UUID or UID)

beaconId2

String

A sub-identifier for the beacon (e.g. major or namespaceId)

beaconId3

String

A sub-identifier for the beacon (e.g. minor or instanceId)

beaconServiceUUID

Integer

The service uuid of the beacon

beaconTxPower

Integer

The transmission power of the beacon

beaconDistance

String

The distance from the users device to the beacon

beaconName

String

The name of the beacon

beaconManufacturer

Integer

The Company Id of the bluetooth device assigned by the Bluetooth SIG. Website: https://www.bluetooth.com/specifications/assigned-numbers/company-Identifiers

beaconTypeCode

String

A 16 byte standard identifier for the iBeacon

beaconURL

String

The URL transmitted by the Eddystone URL beacon

beaconTelemetryVersion

String

The operating system version of the beacon

beaconTelemetryBattery

String

The battery life of the beacon

beaconTelemetryPduCount

String

The advertising PDU count of the beacon

beaconTelemetryUptime

String

The time since last reboot of the beacon

Example
Try this in your terminal, and be sure you have successfully implemented Basic Auth:
curl \
-X POST \
-H "Authorization: Basic NTRkNjkxMzk5MDI1NDQ3OTU0MjA4MTU0ZDY5MTM5OTAyNWY1MzkxMzIwNjU6Y29tLmJlYWNvbmluc3BhY2UuamV0ZnVlbA==" \
-d uuid=99259a46-a024-11e5-8994-feff819cdc9f \
-d major=2434 \
-d minor=2 \
-d userId2=AE2E52E7-03EE-455A-B3C4-E57283966238 \
-d userIdType2=IDFA \
-d detect=exit \
-d createdAt=1458854814.466618 \
https://api.beaconsinspace.com/v1/event
    
Result Format
{
    "code": 200,
    "message": "Success",
    "data": {
        "beaconId": "beaconjR",
        "timezone": "America/New_York",
        "latitude": 42.3514653,
        "longitude": -71.0601767,
        "detect": "exit"
    }
    
logo

REST Examples

We've provided some best practices and examples so you can get started with the API in no time!

logo

Example: Sending GPS Coordinates as Events

Goal: Send GPS coordinates as real-time events for the purposes of analytics and monetization.
1. Let's say you have regular location updates (lat/long) from your app users that you wish to send to BeaconsInSpace in real-time from your client or server. To do this, we use the Event endpoint and pass the required parameters as well as gpsLatitude, gpsLongitude, gpsHorizontalAccuracy, ipAddress and as many of following parameters as you have access to:
Note: If you are sending location data for monetization, more detailed data may make it more valuable. With this in mind, we recommend sending as many of the parameters that you can.
Parameters
*required
Name
Type
Description
*

userId2

String

An identifier that is unique to every user of your app

*

userIdType2

String

The type of userId2. Accepted values are "IDFA", "AAID", or "WINID" (Windows Id)

*

detect

String

Either "gps" if you are passing a gps coordinate OR "enter" or "exit"  if you've entered or exited the proximity of a beacon respectively

*

createdAt

Double

Please pass a UNIX UTC Timestamp. Be as accurate as possible, values to the 6th decimal place are preferred. e.g. 1458854814.466618

ipAddress

String

The IP Address of the users device at the time the event occured

country

String

The country code of the users device. Needs to be 2 characters in ISO 3166-1 alpha 2 format (e.g. US, FR)

os

String

The operating system version of the users device

device

String

The model of the users device (e.g. iPhone 6)

language

String

The language of the users device. Needs to be 2 characters in "ISO 639-1" format (e.g. en, fr)

tz

String

The timezone of the users device

gpsLatitude

String

The latitude coordinates of the users device

gpsLongitude

String

The longitude coordinates of the users device

gpsHorizontalAccuracy

Double

The accuracy of the latitude and longitude, measured in meters

gpsAltitude

Double

The altitude of the device, measured in meters

gpsVerticalAccuracy

Double

The accuracy of the altitude, measured in meters

gpsSpeed

Double

The instantaneous speed of the device in meters per second

gpsFloor

Integer

The logical floor of the building in which the user is located

gpsCourse

Double

The direction in which the device is traveling

gpsBearing

Double

The bearing, in degrees

2. In your terminal paste the code below to make a test call:
curl \
-X POST \
-H "Authorization: Basic NTRkNjkxMzk5MDI1NDQ3OTU0MjA4MTU0ZDY5MTM5OTAyNWY1MzkxMzIwNjU6Y29tLmJlYWNvbmluc3BhY2UuamV0ZnVlbA==" \
-d userId2=AE2E52E7-03EE-455A-B3C4-E57283966238 \
-d userIdType2=IDFA \
-d detect=gps \
-d createdAt=1473292976.466618 \
-d ipAddress=12.2.182.218 \
-d gpsLatitude=37.7844450 \
-d gpsLongitude=-122.4049520 \
-d gpsHorizontalAccuracy=10 \
https://api.beaconsinspace.com/v1/event
    
3. In the response you see a success message that was created:
{
    "code": 200,
    "message": "Success",
    "data": {
        "beaconId": null
    }
    
4. That was easy! You are now ready to start making real-time API calls for analytics and monetization.
logo

Example: Sending Beacon Detections as Events

Goal: Send Beacon Detections as real-time events for the purposes of analytics and monetization.
1. Let's say you detect beacons from your app that you wish to send to BeaconsInSpace in real-time from your client or server. To do this, we use the Event endpoint and pass the required parameters as well as gpsLatitude, gpsLongitude, gpsHorizontalAccuracy, ipAddress and as many of following parameters as you have access to:
Note: If you are sending beacon data for monetization, more detailed data will make it more valuable. With this in mind, we recommend sending as many of the parameters as you can.
Parameters
*required
Name
Type
Description
*

userId2

String

An identifier that is unique to every user of your app

*

userIdType2

String

The type of userId2. Accepted values are "IDFA", "AAID", or "WINID" (Windows Id)

*

detect

String

Either "gps" if you are passing a gps coordinate OR "enter" or "exit"  if you've entered or exited the proximity of a beacon respectively

*

createdAt

Double

Please pass a UNIX UTC Timestamp. Be as accurate as possible, values to the 6th decimal place are preferred. e.g. 1458854814.466618

ipAddress

String

The IP Address of the users device at the time the event occured

country

String

The country code of the users device. Needs to be 2 characters in ISO 3166-1 alpha 2 format (e.g. US, FR)

os

String

The operating system version of the users device

device

String

The model of the users device (e.g. iPhone 6)

language

String

The language of the users device. Needs to be 2 characters in "ISO 639-1" format (e.g. en, fr)

tz

String

The timezone of the users device

gpsLatitude

String

The latitude coordinates of the users device

gpsLongitude

String

The longitude coordinates of the users device

gpsHorizontalAccuracy

Double

The accuracy of the latitude and longitude, measured in meters

gpsAltitude

Double

The altitude of the device, measured in meters

gpsVerticalAccuracy

Double

The accuracy of the altitude, measured in meters

gpsSpeed

Double

The instantaneous speed of the device in meters per second

gpsFloor

Integer

The logical floor of the building in which the user is located

gpsCourse

Double

The direction in which the device is traveling

gpsBearing

Double

The bearing, in degrees

2. In your terminal paste the code below to make a test call:
curl \
-X POST \
-H "Authorization: Basic NTRkNjkxMzk5MDI1NDQ3OTU0MjA4MTU0ZDY5MTM5OTAyNWY1MzkxMzIwNjU6Y29tLmJlYWNvbmluc3BhY2UuamV0ZnVlbA==" \
-d userId2=AE2E52E7-03EE-455A-B3C4-E57283966238 \
-d userIdType2=IDFA \
-d detect=gps \
-d createdAt=1473292976.466618 \
-d ipAddress=12.2.182.218 \
-d gpsLatitude=37.7844450 \
-d gpsLongitude=-122.4049520 \
-d gpsHorizontalAccuracy=10 \
https://api.beaconsinspace.com/v1/event
    
3. In the response you see a success message that was created:
{
    "code": 200,
    "message": "Success",
    "data": {
        "beaconId": null
    }
    
4. That was easy! You are now ready to start making real-time API calls for analytics and monetization.
logo

Questions & Feedback

Community

Join our #Slack community and chat with us and your fellow community members live!

Security

Security is serious. We are committed to upholding the highest standards to ensure that your data and the applications you're building are secure.

If you have questions on our security protocols please contact us at security@beaconsinspace.com.

logo