endpoint and authentication

Please refer to the API overview section to get the API endpoint, query format and authentication process.

List locations recorded on one application

GET /api/apps/app_identifier/locations?page=page&per_page=per_page&fields=fields&session_ids=session_ids&device_ids=device_ids&latitude=latitude&longitude=longitude&since_date=since_date&until_date=until_date

CSV Export endpoint (see how to use it here):

GET /api/apps/app_identifier/locations_export?fields=fields&session_ids=session_ids&device_ids=device_ids&latitude=latitude&longitude=longitude&since_date=since_date&until_date=until_date

Property Type Description Default
app_identifier string The app unique identifier required
page integer The page of devices to retrieve. Negative values will be ignored, and the default number will be used. 1
per_page     integer   The number of device ids to retrieve per page.
Range of values accepted is [1..10000]. Values outside of range are ignored, and the default value is used instead.  
1000
fields string A string with a list of device fields to present, separated by commas. Example: fields=device_id,longitude. If there's no value for some field requested, the value null is returned for that field.
See table below for possible fields.
-
session_ids string List of comma-separated session_id's to filter to filter the locations only for the provided sessions -
device_ids string List of comma-separated device_id's to filter the locations only for the provided devices -
latitude Decimal A floating point number which will filter the locations for the app only for that latitude -
longitude Decimal A floating point number which will filter the locations for the app only for that longitude -
since_date datetime The date in UTC since when locations should be fetched. Expressed in any ISO format, e.g. 2017-04-06T16:41:44+05:00. -
until_date datetime The date in UTC until when locations should be fetched. Expressed in any ISO format, e.g. 2017-04-06T16:41:44+05:00. -

Response fields

Value Type Description
location_id string Always returned The unique identifier of the location
device_id string Unique identifier of the device
application_id string Unique identifier of the application
latitude Decimal Decimal number representing the latitude of the location
longitude Decimal Decimal number representing the longitude of the location
session_id string Unique identifier of the session associated with the location
user_id string Unique identifier of the user id associated with the location
date_utc datetime Date and time of the location in UTC

Response

Status: 200 OK

{
  "result": {
    "items": [
      {
        "location_id": "51a38a4c239e634f310000c8-locs-00000",
        "longitude": 2.314179,
        "latitude": 48.875143,
        "application_id": "FAAPPLI_Fr5tg2e",
        "user_id": "user@myuser",
        "session_id": "51a38a64239e634f3b0000cc"
      },
      {
        "location_id": "51a38a4c239e634f310000c8-locs-00001",
        "longitude": 2.314172,
        "latitude": 48.873245,
        "application_id": "FAAPPLI_Fr5tg2e",
        "user_id": "user@myuser",
        "session_id": "51a38a64239e634f3b0000cc"
      },
    ],
    "total_pages": 4,
    "total_items": 20,
    "item_count": 2,
    "navigation": {
      "first": "http://api.follow-apps.com/api/apps/FAAPPLI_Fr5tg2e/locations?page=1&fields=user_id,application_id,latitude,longitude",
      "prev": "http://api.follow-apps.com/api/apps/FAAPPLI_Fr5tg2e/locations?page=1&fields=user_id,application_id,latitude,longitude",
      "next": "http://api.follow-apps.com/api/apps/FAAPPLI_Fr5tg2e/locations?page=2&fields=user_id,application_id,latitude,longitude",
      "last": "http://api.follow-apps.com/api/apps/FAAPPLI_Fr5tg2e/locations?page=4&fields=user_id,application_id,latitude,longitude"
    }
  },
  "success": true
}

Status: 404 not found

{
    "status": "not_found",
    "success": false,
    "error_message": "Couldn't find App"
}

Status: 400 bad request

{
  "success": false,
  "status": "bad_request",
  "error_message": "Wrong date format"
}

List locations recorded on one entity

GET /api/locations

This API lists all the locations for the user making the request.

Response

Status: 200 OK

{
  "success": true,
  "result": [
    {
      "name": "Location Name",
      "identifier": "FALOC_123321",
      "labels": ["label", "label2"],
      "details": "Some locations details",
      "latitude" 10.231231,
      "longitude": -10.23123,
      "archived": false,
      "archived_at": null,
    },
    {
      "name": "Location Name",
      "identifier": "FALOC_123321",
      "labels": ["label", "label3"],
      "details": "Some locations details",
      "latitude" 10.231231,
      "longitude": -10.23123,
      "archived": false,
      "archived_at": null,
    }
  ]
}

When the entity associated with the user making a request can't be found:

Status: 404 not found

{
  "status": "not_found",
  "success": false,
  "error_message": "Entity not found"
}

View

GET /api/locations/identifier

Returns a specific location.

Query Parameters

Property Type Description Default
identifier string The identifier of the location to view required

Response

Status: 200 OK

{
  "success": true,
  "result": {
    "name": "Location Name",
    "identifier": "FALOC_123321",
    "labels": ["label", "label3"],
    "details": "Some locations details",
    "latitude" 10.231231,
    "longitude": -10.23123,
    "archived": false,
    "archived_at": null,
  }
}

When the entity associated with the user making a request can't be found:

Status: 404 not found

{
  "status": "not_found",
  "success": false,
  "error_message": "Location not found"
}

When the location doesn't exist or does not belong to the entity:

Status: 404 not found

{
  "status": "not_found",
  "success": false,
  "error_message": "Location not found"
}

Create

POST /api/locations

Creates a new location on the entity of the request, provided the user has permissions.

You can also create several locations at once by using the import API.

Body Parameters

Property Type Description Default
name string A name for your location required
details string A string with details for your location -
latitude decimal The latitude of the location. The value must be between -90 and 90 required
longitude decimal The longitude of the location. The value must be between -180 and 180 required
labels array of strings The label names to add to your location -

Example

{
  "name": "test location",
  "details": "test details",
  "latitude": 10.20,
  "longitude": 20.22,
  "labels": ["a", "b", "c"],
}

Status: 200 OK

{
  "success": true,
  "result": {
    "name": "test location",
    "identifier": "FALOC_123321",
    "labels": ["a", "b", "c"],
    "details": "test details",
    "latitude" 10.20,
    "longitude": 20.22,
    "archived": false,
    "archived_at": null,
  }
}

When the entity associated with the user making a request can't be found:

Status: 404 not found

{
  "status": "not_found",
  "success": false,
  "error_message": "Location not found"
}

When the the user doesnt have permissions to create locations:

Status: 404 not found

{
  "status": "forbidden",
  "success": false,
  "error_message": "No access."
}

Update

PUT /api/locations/identifier

Updates the data of a location, provided the user has permissions to do it. Please note that the only fields that can be changed for a location are: the location name, details and labels. The coordinates (latitude and longitude) are read only.

Query Parameters

Property Type Description Default
identifier string The identifier of the location to update required

Body Parameters

Property Type Description Default
labels array of strings The new labels to update the location with -
name string The new location name -
details string The new location details -

Example

{
    "labels": ["123", "test", "other"],
    "name" "new location name",
    "details": "new location details"
}

Response

Status: 200 OK

{
  "success": true,
  "result": {
    "name": "new location name",
    "identifier": "FALOC_123321",
    "labels": ["123", "test", "other"],
    "details": "new location details",
    "latitude" 10.20,
    "longitude": 20.22,
    "archived": false,
    "archived_at": null,
  }
}

When the entity associated with the user making a request can't be found:

Status: 404 not found

{
  "status": "not_found",
  "success": false,
  "error_message": "Location not found"
}

When the the user doesnt have permissions to update locations:

Status: 404 not found

{
  "status": "forbidden",
  "success": false,
  "error_message": "No access."
}

Archive

PUT /api/locations/identifier/archive

This API endpoint archives a location, making it unnaccessible, provided the user has permissions to do it. An archived location cannot be used when defining the filters of a new campaign and/or segment.

Query Parameters

Property Type Description Default
identifier string The identifier of the location to archive required

Response

Status: 200 OK

{
  "success": true,
  "result": {
    "name": "new location name",
    "identifier": "FALOC_123321",
    "labels": ["123", "test", "other"],
    "details": "new location details",
    "latitude" 10.20,
    "longitude": 20.22,
    "archived": true,
    "archived_at": "2018-03-07T15:36:44.924Z",
  }
}

When the entity associated with the user making a request can't be found:

Status: 404 not found

{
  "status": "not_found",
  "success": false,
  "error_message": "Location not found"
}

When the the user doesnt have permissions to update locations:

Status: 404 not found

{
  "status": "forbidden",
  "success": false,
  "error_message": "No access."
}

Restore

PUT /api/locations/identifier/restore

This API endpoint restores a location, making it accessible again, provided the user has permissions to do it. It will be visible again when defining the filters of a new campaign and/or segment.

Query Parameters

Property Type Description Default
identifier string The identifier of the location to restore required

Response

Status: 200 OK

{
  "success": true,
  "result": {
    "name": "new location name",
    "identifier": "FALOC_123321",
    "labels": ["123", "test", "other"],
    "details": "new location details",
    "latitude" 10.20,
    "longitude": 20.22,
    "archived": false,
    "archived_at": null,
  }
}

When the entity associated with the user making a request can't be found:

Status: 404 not found

{
  "status": "not_found",
  "success": false,
  "error_message": "Location not found"
}

When the the user doesnt have permissions to update locations:

Status: 404 not found

{
  "status": "forbidden",
  "success": false,
  "error_message": "No access."
}

Downloading an import template

GET /api/location/generate_import_template?template_format

This API generates an import template that you can use to create locations in batch. You can specify the template format that you wish to generate.

Currently allowed template formats:

Query Parameters

Property Type Description Default
template_format string A template format. csv

Response

When an unsupported template format is requested (for example: json)

Status: 200

{
  "status": "bad_request",
  "success": false,
  "error_message": "Unsupported import template: json"
}

Importing locations in batch

POST /api/location/import

This API allows you to import a list of locations in batch. You should utilize a template generated by the import template generation api.

Currently supported file formats: the same formats supported by the import template generation api.

Note: The server will force encode the location data (name, details, labels, etc) to UTF-8 encoding, so make sure your file is correctly converted to utf-8 before uploading to guarantee better results.

Body Parameters

Property Type Description Default
file file The import file -

Response

When an unsupported template format is requested (for example: json)

Status: 200

{
  "status": "bad_request",
  "success": false,
  "error_message": "Unsupported import template: json"
}

Response

When an unsupported template format is requested (for example: json)

Status: 200

{
  "status": "bad_request",
  "success": false,
  "error_message": "Unsupported import template: json"
}