REST API: List Locations

Last Updated: October 16, 2018

Description

Retrieves a list of all locations associated with your company, with optional filters to narrow down the results.

Resource Information

HTTP Method GET
Endpoint https://rest.tsheets.com/api/v1/locations
Authentication Token header required. See authentication section
Request format Everything is handled through the request uri on a GET.
Response format json
Response object Location

Available Filters

ids:
optional
Integer. Comma separated list of one or more location ids you'd like to filter on. Only locations with an id set to one of these values will be returned. If omitted, all locations matching other specified filters are returned.
active:
optional
String. 'yes', 'no', or 'both'. Default is 'yes'. If a location is active, it is available for selection during time entry.
geocoding_status:
optional
String. Comma separated list of one or more of the following values: 'none', 'in_progress', 'retry', 'error', or 'complete'. If omitted, all locations matching other specified filters are returned.
modified_before:
optional
String (ISO8601 format). Only locations modified before this date/time will be returned (i.e. 2004-02-12T15:19:21+00:00).
modified_since:
optional
String (ISO8601 format). Only locations modified since this date/time will be returned (i.e. 2004-02-12T15:19:21+00:00).
supplemental_data:
optional
String. 'yes' or 'no'. Default is 'yes'. Indicates whether supplemental data should be returned.
per_page:
optional
Integer. Represents how many results you'd like to retrieve per request (page). Default is 50. Max is 50.
page:
optional
Integer. Represents the page of results you'd like to retrieve. Default is 1.
by_jobcode_assignment:
optional
Boolean. true or false. If specified only locations mapped to a jobcode the user is assigned to will be returned.

Examples

Retrieve a list of all active locations.

## REQUEST
curl -H "Authorization: Bearer <Access-Token>" -i "https://rest.tsheets.com/api/v1/locations"

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

{
 "results": {
  "locations": {
   "65305": {
    "id": 65305,
    "addr1": "235 E Colchester Dr",
    "addr2": "101",
    "city": "Eagle",
    "state": "ID",
    "zip": "83616",
    "country": "US",
    "formatted_address": "235 E Colchester Dr 101, Eagle, ID 83616",
    "active": true,
    "latitude": 43.6700273,
    "longitude": -116.3520972,
    "place_id": "",
    "place_id_hash": "0ba5eaf96c5f63c3b76d5084c365b6e4",
    "label": "TSheets, East Colchester Drive, Eagle, ID, USA",
    "notes": "",
    "geocoding_status": "complete",
    "created": "2018-03-09T18:26:57+00:00",
    "last_modified": "2018-03-15T16:51:14+00:00",
    "linked_objects": {
     "jobcodes": [
      2589531
     ]
    },
    "geofence_config_id": null
   },
   "78135": {
    "id": 78135,
    "addr1": "Hollywood Blvd",
    "addr2": "",
    "city": "Los Angeles",
    "state": "CA",
    "zip": "",
    "country": "US",
    "formatted_address": "Hollywood Blvd, Los Angeles, CA",
    "active": true,
    "latitude": 34.1015885,
    "longitude": -118.3336436,
    "place_id": "",
    "place_id_hash": "8c43103323bb0b1ce7c4094029029914",
    "label": "Hollywood Boulevard, Los Angeles, CA, USA",
    "notes": "",
    "geocoding_status": "complete",
    "created": "2018-03-19T22:52:04+00:00",
    "last_modified": "2018-04-19T16:29:14+00:00",
    "linked_objects": {},
    "geofence_config_id": 1393
   }
  }
 },
 "more": false,
 "supplemental_data": {
  "jobcodes": {
   "2589531": {
    "id": 2589531,
    "active": true,
    "parent_id": 0,
    "assigned_to_all": false,
    "type": "regular",
    "billable": false,
    "billable_rate": 5,
    "short_code": "",
    "name": "Technology",
    "created": "2018-03-15T15:50:50+0000",
    "last_modified": "2018-03-15T23:09:27+0000",
    "has_children": false,
    "required_customfields": [],
    "filtered_customfielditems": "",
    "locations": [
     65305
    ]
   }
  },
  "geofence_configs": {
   "1393": {
    "id": 1393,
    "active": true,
    "type": "locations",
    "type_id": 78135,
    "enabled": true,
    "radius": 125,
    "created": "2018-05-20T12:34:56+00:00",
    "last_modified": "2018-05-20T12:34:56+00:00"
   }
  }
 }
}
    

Retrieve a list of all locations (active or deleted) with geocoding_status of 'complete'. Set pagination to 10 results/page.

## REQUEST
curl -H "Authorization: Bearer <Access-Token>" -i "https://rest.tsheets.com/api/v1/locations?geocoding_status=complete&per_page=10&active=both"

## RESPONSE
## (response would have the same layout as the above examples)
    

Retrieve a list of locations with ids 12, 367, and 3489.

## REQUEST
curl -H "Authorization: Bearer <Access-Token>" -i "https://rest.tsheets.com/api/v1/locations?ids=12,367,3489"

## RESPONSE
## (response would have the same layout as the above examples)
    

Retrieve a list of locations that have been modified since Jan 1, 2013

## REQUEST
## Note that instead of a plus, we're using '%2B', the url-encoded equivalent - to prevent the + getting replaced by a space.
curl -H "Authorization: Bearer <Access-Token>" -i "https://rest.tsheets.com/api/v1/locations?modified_since=2013-01-01T00:00:00%2B00:00"

## RESPONSE
## (response would have the same layout as the above examples)