Key Concepts
A few key concepts to remember – as long as you get these right, you are good to go!
- Test cases
- Triggers
- Webhooks
- Places
- Groups
Test cases
You create test cases to define your testing scenarios. As an example you have a ‘free parking finder’ application that users can use while driving to find parking in various neighborhoods. To test your application’s behavior in various neighborhoods you would create one or more test cases.
Create a new test case attached to a place, places, areas, neighborhoods etc. Create a test area where you want to simulate your user’s motion.
Get all the test cases you have associated with your application and account.
Get the test case type – i.e whether it is ‘By Address’, ‘By Polygon’, ‘By Circle’ etc.
Delete a test case that you had previously created.
Use this method to get lat/long combination for random points on a polyline, inside a polygon or within a circular area.
Use this method in your test case when you are specifying an address combination (start-end). In other words, use this method if you want to simulate a user walking or driving.
This is very similar to GetDirectionPoint API. It allows you to simulate and get sequential points on a ‘polyline’/aka any random path that you defined in your testcase.
Triggers
Triggers allow you to create alerts/notifications if your application’s users are within a pre-determined distance from an area or in an area that’s of interest to either you or marketers. Think of monitoring a user’s location and alerting him/her with a deal coupon if he/she is near a specific store.
Use this method to get a list of your triggers associated with your application/account.
Use this method to delete a trigger that you previously created.
Use this method to create your triggers – (e.g. inside polygon, distance to polygon, inside circle, distance to circle, on polyline, distance to polyline etc).
Use this method to check if you trigger matched or satisfied the conditions you set/determined.
Webhooks
Webhooks allow you to keep your application’s backend in synch with what’s happening in your application’s front end. In other words, if you are using our APIs/SDKs to create triggers, execute triggers, show ads based on triggers etc.. you would want to keep your backend server (for your application) in sync with the actions we are taking – use webhooks to do this. The same trigger that went out to your application will show up on your backend server. Here’s an example:
If you have your backend appserver listening on a url like
http://yourawesomeapp.com/webhook.php
GeoLoqal will send the following info back to your app..
http://yourawesomeapp.com/webhook.php?trigger_name=YOUR_TRIGGER_NAME&latitude=42.6686898&longitude=-85.555788&status=true&time=2012-10-27 08:59:55
Places
Places or POI APIs allow you to get POI/places data from various providers (including google, bing, yahoo, mapquest and GeoLoqal). This is a perfect way to increase your users’ engagement with your application and the added value you can provide your users with your application.
Basic attributes of places include Name, Address, Phone Number, Latitude/Longitude, Category, Email, Website, and Open/Close Status (wherever available). You can also get more interesting attributes for POI data like shopping, restaurants, accommodation, gas, tourist locations, transportation, WiFi hotspots, ATM etc.
Use this to get places/POI data around your user’s location.
Groups
Groups basically allow you to define large scale test cases and triggers. Imagine this – you have an app that you want to test around all the Starbucks locations in NYC or you want to geofence your users around every CitiBank ATM around town. Instead of creating triggers or test cases and testing them individually, just assign them all to one group. This will allow you to test your app in all or any those locations. The triggers would fire if your user is walking around any of these locations. In addition to this, you can also group various different places together. Say you have geofenced a bunch of businesses in Chelsea and you want to fire a trigger/alert if a user is near any of those businesses – just put them in a group and you are done. For situations where you want to fire an alert or a trigger only when a user is around a Bank of America location and a Starbucks – call the trigger with the option ‘all’. That’s it – that simple – no really!
Use this method to check if your trigger matched any or all of the groups that you have defined for your triggers.
