REST API: Add Geolocations

Last Updated: July 08, 2015

Description

Add one or more geolocations. We will handle batches of up to 50 geolocations at a time. More than 50 geolocations will result in a 413 - Request entity too large error.

Resource Information

HTTP Method POST
Endpoint https://rest.tsheets.com/api/v1/geolocations
Authentication Token header required. See authentication section
Request format json object. Pass an array of geolocation objects as the value to a 'data' property (see example below).
Response format json
Response object Geolocation

Required Geolocation properties

id:
Integer. Read-only. Id of geolocation.
user_id:
Integer. User id for the user that this timesheet belongs to.
accuracy:
Integer. Indicates the radius of accuracy around the geolocation in meters.
altitude:
Float. Indicates the altitude of the geolocation in meters. Enter 0 if altitude is unknown.
latitude:
Float. Indicates the latitude of the geolocation in degrees.
longitude:
Float. Indicates the longitude of the geolocation in degrees.
created:
String (ISO8601 format). Date/time when this geolocation was created (i.e. 2004-02-12T15:19:21+00:00). Must be less than or equal to the current time.
device_identifier:
String. Unique identifier (for the given client) for the device associated with this geolocation.

Optional Geolocation Properties

For a full list of the properties that may be set on a geolocation, see the Geolocation object.

Status Codes

Each geolocation that is created will come back with a _status_code and _status_message that will indicate whether the geolocation was created successfully. If there was a problem creating a geolocation, there may also be an additional field, _status_extra, which will contain more details about the failure.

_status_code Meaning
200 OK. geolocation was created successfully.
202 OK. geolocation was accepted, but not created (because we already have a geolocation with all the same characteristics as the submitted one)
417 Expectation Failed. Something was wrong or missing with the properties supplied for this geolocation. See the _status_extra value for more detail.

Examples

Create two new geolocations.

## REQUEST
curl -H "Authorization: Bearer <Access-Token>" -X POST -i -H "Content-Type: application/json" -d @geolocation_create.json "https://rest.tsheets.com/api/v1/geolocations"

## contents of the geolocation_create.json file are:
{
 "data":
  [
    {
     "created": "2013-08-19T11:30:09-06:00",
     "user_id": 1242515,
     "accuracy": 20,
     "altitude": 0,
     "latitude": 43.68662580,
     "longitude": -116.35166460
    },
    {
     "created": "2013-08-19T12:38:56-06:00",
     "user_id": 1242515,
     "accuracy": 20,
     "altitude": 0,
     "latitude": 43.68692580,
     "longitude": -116.35169460
    }
  ]
}



## RESPONSE
HTTP/1.1 200 OK
Content-Type: application/json

{
 "results": {
  "geolocations": {
   "1": {
    "_status_code": 200,
    "_status_message": "Created",
    "id": 185899164,
    "user_id": 1242515,
    "accuracy": 20,
    "altitude": 0,
    "latitude": 43.6866258,
    "longitude": -116.3516646,
    "created": "2013-08-19T17:30:09+00:00"
   },
   "2": {
    "_status_code": 200,
    "_status_message": "Created",
    "id": 185899166,
    "user_id": 1242515,
    "accuracy": 20,
    "altitude": 0,
    "latitude": 43.6869258,
    "longitude": -116.3516946,
    "created": "2013-08-19T18:38:56+00:00"
   }
  }
 },
 "supplemental_data": {
  "": {
   "1242515": {
    "id": 1242515,
    "first_name": "Alexander",
    "last_name": "Luzzana",
    "group_id": 144959,
    "active": true,
    "employee_number": 4,
    "salaried": true,
    "exempt": false,
    "username": "aluzzana",
    "email": "garrett@tsheets.com",
    "payroll_id": "",
    "hire_date": "2012-07-01",
    "term_date": "0000-00-00",
    "last_modified": "2013-07-12T15:52:00+00:00",
    "last_active": "2013-08-22T22:09:37+00:00",
    "created": "2013-05-28T20:23:44+00:00",
    "mobile_number": ""
   }
  }
 }
}