Location Methods

The location methods are used to create, update, delete or get info on locations associated with your app. By adding locations to your app you will begin to gather analytics on devices entering an exiting those locations. You can also ad Locations to campaigns to create location based campaigns. Available Methods are:

 

• Create: Create a geo-fence or iBeacon location
• Update: Update an existing a location
• Delete: Delete an existing location
• List: Query existing campaigns and get a list of results
• Info: Get info on a single location 

 

Create

Used to create a Location that will be associated with your app. The location may be a geo-fenced or an iBeacon-fenced region.

URL

api/external/create/location

Parameters

Parameter	Description
apptoken	Your App token
title	A name used to identify your location e.g. Main St. Store
address	The address of your location
tags	List of location tags separated by comma
latitude	Floating point latitude co-ordinate e.g. 53.342123
longitude	Floating point longitude co-ordinate e.g. -6.283218
radius	Integer value for the radius of your geo-fence or iBeacon fence region units are metres
country	Two character country code (ISO 3166-1 alpha-2) e.g. IE
type	Integer, location type 0 - Geo Location 2 - iBeacon
ibeacon_uuid	iBeacon UUID: String value in format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
ibeacon_major	iBeacon major: Integer value from 0 to 65535
ibeacon_minor	iBeacon minor: Integer value from 0 to 65535

Example

Creating an iBeacon location.

curl -X POST -d '{"apptoken":"YOUR_APPTOKEN", "title":"Hackathon Beacon 100", "address":"Digital Exchange, Crane Street, Dublin 8", "tags":"Hackathon, Dublin", "radius": 20, "latitude":53.342123, "longitude":-6.283218, "country":"IE", "type":2, "ibeacon_uuid": "7F01E2E7-F0E3-4124-8F5F-B1CC21530B4D", "ibeacon_major":100, "ibeacon_minor":100}' https://external-api.xtremepush.com/api/external/create/location

Example response from a successfully created location, this location is an iBeacon-fenced region.

{
    "code": 200,
    "success": true,
    "message": "Location successfully created",
    "model": {
        "id": LOCATION_ID,
        "project_id": PROJECT_ID,
        "title": "Hackathon Beacon 100",
        "address": "Digital Exchange, Crane Street, Dublin 8",
        "country": "IE",
        "groups_str": "Hackathon, Dublin",
        "latitude": 53.342123,
        "longitude": -6.283218,
        "radius": 20,
        "type": 2,
        "ibeacon_uuid": "7F01E2E7-F0E3-4124-8F5F-B1CC21530B4D",
        "ibeacon_major": 100, 
        "ibeacon_minor": 100,
    }
}

 

Update

Used to update a previously created Location associated with your app. The location may be a geo-fenced or an iBeacon-fenced region.

URL

api/external/update/location

Parameters

Parameter	Description
apptoken	Your App token
id	The id of the location being updated
more params	The other params are the same as those available in the create method

Example

Updating the radius of location

curl -X POST -d '{"apptoken":"YOUR_APPTOKEN", "id":LOCATION_ID, "radius": 50}' https://external-api.xtremepush.com/api/external/update/location | python -m json.tool

 

Delete

Used to delete a previously created location.

URL

api/external/delete/location

Parameters

Parameter	Description
apptoken	Your App token
id	The id of the location being deleted

Example

Example of deleting a location

curl -d 'apptoken=YOUR_APPTOKEN&id=LOCATION_ID' https://external-api.xtremepush.com/api/external/delete/location

 

List

Used to get a list of all the locations associated with your App. All locations may be returned or lists of a certain type of location if specific criteria are provided.

URL

api/external/list/location

Parameters

Parameter	Description
apptoken	Your App token
order	Order the list in either ascending or descending order based on any of the attributes e.g. "order": ["ibeacon_uuid", "ibeacon_major"] or "order": ["id DESC"]
select	Select what attributes to return e.g. "select": ["country", "addres"]
condition	Filter the returned push actions based on some criteria e.g. "condition": [["country", "=" , "IE"]]
limit	Used with offset for pagination e.g. "limit: 50, "offset": 0 returns a max of 50 items starting at position 0
offset	Used with limit for pagination e.g. "limit": 50, "offset": 0 returns a max of 50 items starting at position 0

Example

Return the location info for the locations in Ireland.

curl -X POST -d '{"apptoken":"YOUR_APPTOKEN", "condition": [["country","=","IE"]]}' https://external-api.xtremepush.com/api/external/list/location

 

Info

Used to get info on a single location.

URL

api/external/info/location

Parameters

Parameter	Description
apptoken	Your App Token
id	The id of the location you are looking for
select	Select what attributes to return e.g. "select": ["id", "title", "address"]

Example

Return the country and address for the location with the given id.

curl -X POST -d '{"apptoken":"YOUR_APPTOKEN", "id":LOCATION_ID, "select": ["id", "title", "address"]}' https://external-api.xtremepush.com/api/external/info/location