Leveraging the Power of Public APIs to Interact with Bluedot Systems – Part 1

The public APIs form a crucial part of our advanced location services technology stack. They allow our customers and partners to efficiently and programmatically create and manage locations, actions, and conditions in a scalable manner.

These locations, actions, and conditions are downloaded by mobile devices as business rules to enable interactions with app users when they enter or exit the locations. The Public APIs are also the primary way our customers consume data captured through check-in and check out events. As the APIs have been designed and built for performance and scale, they are extremely fast and handle large volumes of data easily. The APIs are based entirely on JSON and the request and response structures are easy to digest and code against. We are very proud of these non-stop hard workers and the balance they provide between flexibility and security, fault tolerance, and performance.

Throughout this post, Postman tool is used to demonstrate HTTP requests. There are other similar easy to use tools that can be used to achieve the same results.

In this post, I wanted to walk through the process of creating Application, Zone, Geofence, Geoline™, Action and Condition.

Creating an Application

In order to create an application, you need your main API key called Customer API key, which can be found in the welcome email you received after creating a Bluedot account. It can also be found in the Account Management section in Point Access user interface. The “Customer API Key” is the identification key used by the applications API to create an application. A Bluedot backend application acts as a container for zones. A mobile app that uses the Bluedot Point SDK for location features will use the Application API key, Package name, and username parameters to authenticate with the Bluedot systems. The idea is to have a backend application mapped to a mobile app.

To create an application, send a POST request to https://api.bluedot.io/1/applications API.

JSON template to create an Application:

{  
   "security":{  
      "customerApiKey":"Your customer API Key"
   },
   "content":{  
      "application":{  
         "name":"Application for public API demo - Part1",
         "packageName":"com.bluedotinnovation.publicapiblogpartone",
         "nextRuleUpdateIntervalFormatted":"24:00"
      }
   }
}

Creating an application:

Creating a zone

We have a backend application and are now ready to create zones under the application. A zone is a container for Geofences, Geoline™, Bluetooth beacons, Actions, and Conditions. The design and structure of the zone allow us to combine all of the Geo elements, temporal and other conditions to trigger an action on the mobile device to engage users based on their behaviors. There are no limitations on the number of zones the platform can handle.

For the purposes of the walk through, we will create a zone at Entrance 1 of a football field. The zone will display a welcome message and deliver the user, a URL pointing to the detailed map of the stadium so the visitors can navigate the stadium freely. Just so we won’t deliver the notifications every single time the user walks into the venue, we will configure the zone to re-trigger once every 24 hours. This ensures the user will only receive one set of notifications per 24 hours even if they visited the venue several times throughout the day. The messages are only delivered to the users who are walking into the stadium from outside not when they enter into the Geofence from inside, we will add a bearing condition to engage with the users entering the venue from outside. We will also make sure the zone reacts to the users between 9:00 am and 11:00 pm to match the daily hours of the stadium.

To create a zone, send a POST request to https://api.bluedot.io/1/zones API.

JSON template to create a zone:

 {  
   "security":{  
      "customerApiKey":"Your customer API Key",
      "apiKey":"your ApiKey"
   },
   "content":{  
      "zone":{  
         "zoneName":"Football ground campaign - Entrance 1",
         "minimumRetriggerTime":"24:00",
         "enableCheckOut":false,
         "timeActive":{  
            "from":{  
               "time":"09:00",
               "period":"am"
            },
            "to":{  
               "time":"11:00",
               "period":"pm"
            }
         }
      }
   }
}

Creating a zone:

Creating Geofences and Geolines™

We have successfully created a zone under the application in the previous call to zones API. The Zone is now ready to accept Geofences, Geoline™ tripwires, and Beacons. The number of Geofences and Geoline™ technology added to a zone will depend on the use case and user experience of the mobile app. The way to think about it is to map a zone to a mobile campaign, in this example, the football ground is the location that underpins the campaign and the interaction that occurs when the app users get to the location is specific to this location, therefore the Geofences and the interaction are bound to a single zone. This provides the flexibility to tweak the location settings or the interaction without affecting other campaigns.

There are no limitations to the number of Geofences and Geoline™ technology that can be added to a single zone, however, adding all of your locations to a single zone prevents us from segmenting locations into multiple campaigns for future flexibility. There are four different types of Geofences that can be added to zones: Geoline™, Circle, Rectangle, or Polygon. The following example shows a circular Geofence with the 50 meter radius being created at the entrance.

To create Geofences and Geoline™ tripwires, send a POST request to https://api.bluedot.io/1/fences.

JSON template to create a circular Geofence:

{  
   "security":{  
      "customerApiKey":"Your Customer Api Key ",
      "apiKey":"your ApiKey "
   },
   "content":{  
      "zone":{  
         "zoneId":"Your Customer Zone ID",
         "fences":{  
            "circles":[  
               {  
                  "name":"Football ground campaign - Entrance 1",
                  "color":"#000fff",
                  "radius":50,
                  "center":{  
                     "latitude":-37.81890391065329,
                     "longitude":144.9827527999878
                  }
               }
            ]
         }
      }
   }
}

Creating a Geofence:

When the above API request is executed, a circular Geofence with a radius of 50 Meters is created at Entrance 1 of the Football field. The Zone and the Geofence can now be viewed and edited via the Point Access User interface if needed. The angle of arrival for engaging users who enter from outside is also highlighted.

Adding Actions and Conditions to a zone

Actions are the engagement mechanism and conditions govern when the engagement occurs as the app users enter or leave the locations.

The following actions are currently supported and a zone can have one or more of these:

a) Message - send a system notification as a location notification generated by the SDK

b) URL - open a specified URL, this can be any known URL

c) Custom - deliver a callback to the mobile app to allow any custom actions to be executed on the device. This is the most flexible action as the app can build in any additional experiences and customize the engagement.

Each action can have one or more of the following conditions:

Date Range - condition ensures that an action would be triggered within a specific date range.

Time Active - condition ensures that an action would be triggered within a specific time range.

Percentage crossed - condition configures the percentage of fences in a Zone that must be passed by an end user's device in order for the action to be triggered, optionally in a specific sequence.

Speed range - condition ensures that an action would be trigger on a particular speed range.

Bearing range - condition ensures that an action would be trigger on a particular bearing range.

To create actions with conditions, send a POST request to https://api.bluedot.io/1/actions.

JSON template to create a message action with a Bearing condition:

{  
   "security":{  
      "customerApiKey":"Your Customer Api Key ",
      "apiKey":"your ApiKey "
   },
   "content":{  
      "zone":{  
         "zoneId":"Your Customer Zone ID",
         "actions":{  
            "messageActions":[  
               {  
                  "name":"Football ground welcome message!",
                  "title":"Welcome to the Football ground!",
                  "message":"Welcome to the Football Ground, For your convenience, we have got you a map of the venue to make navigation easy",
                  "conditions":{  
                     "bearing":[  
                        {  
                           "fromAngle":280,
                           "toAngle":10
                        }
                     ]
                  }
               }
            ]
         }
      }
   }
}

Creating a message action:

JSON template to create a URL action with a Bearing condition:

{  
   "security":{  
      "customerApiKey":"Your Customer Api Key ",
      "apiKey":"your ApiKey "
   },
   "content":{  
      "zone":{  
         "zoneId":"Your Customer Zone ID",
         "actions":{  
            "urlActions":[  
               {  
                  "name":"Football Ground map",
                  "url":"http://www.mcg.org.au/_/media/files/mcg/general/t20i-mcg-seating-plan-201516.pdf",
                  "conditions":{  
                     "bearing":[  
                        {  
                           "fromAngle":280,
                           "toAngle":10
                        }
                     ]
                  }
               }
            ]
         }
      }
   }
}

Creating a URL action: 

In Part 2, we will learn how to create a zone with Geofence, Geoline™, Beacons, Actions, and Conditions in a single call and look at retrieving data records through the GET APIs.

[panel type="primary"]

Farhan Bava is a Full Stack Developer Intern at Bluedot who is passionate about applying software to solve real world problems. If he's not wrangling lines of code, he's at home tending to his aquarium. [/panel]