Revision as of 19:42, 2 August 2012

Calling GCAPI

A basic call to GCAPI looks like this:

http://[como-URL]/api/[api-subsystem].php?passcode=[my-passcode]&op=[operation]&encoding=[json|xml]

The como URL and passcode are from the results of a GCManage API remote login call. The como URL is what GCManage determines is the path to the como system. This can either be proxied or the direct IP of the system. passcode is the authentication mechanism used by GCAPI -- it is a code generated every 24 hours by a system and reported to GCManage. subsystem names the subsystem you want to work on and operation defines the actual operation to perform. Each operation can have a number of other parameters that will be passed via other parameters in the URL.

Local Application Authentication

Applications may also want to call the API without an associated GCManage account. GrandCare will provide each application an "application key" that allows for a simple way to fetch the required passcodes. To do this, call the API via "localhost" using the following URL:

http://[como-URL]/api/system.php?op=getpasscodes&appkey=[gc-provided-app-key]

This will return the required passcodes for making authenticated calls to the API. See the section on the System API Subsystem for more information about the getpasscodes API call.

Results From GCAPI

The response from GCAPI will either be encoded in JSON or XML, depending on the requested encoding. By default the response will be encoded in XML.

XML Results

By default, GCAPI responds to commands by returning an XML document. Here is the most basic success result:

<gcapi>
   <result>SUCCESS</result>
</gcapi>

The root XML element for all GCAPI results is gcapi. The other always present element is result, which contains either SUCCESS or FAILURE, depending on whether the call succeeded or not. A failure response also contains the fail-message element, which gives the reasons for the failure. For example:

<gcapi>
   <result>FAILURE</result>
   <fail-message>Invalid credentials for API call</fail-message>
</gcapi>

This result would occur if invalid credentials were supplied during the GCAPI call.

JSON Results

GCAPI can also respond by returning a JSON object. Here is the most basic success result:

{
   "gcapi": {
       "result": "SUCCESS"
   }
}

A failure encoded in JSON looks like:

{
   "gcapi": {
       "result": "FAILURE",
       "fail-message": "Invalid credentials for API call"
   }
}

API Subsystems

History

The History subsystem allows you to fetch ADL and wellness data from a system. All of the operations take the same parameters and return different data.

bp

Fetches blood pressure sensor history from the system

Parameters

limit - [optional] - Limits the number of entries returned. Defaults to 50
offset - [optional] - Skip this number of entries. Useful for paging
date - [optional] - Returns only entries for this date
days - [optional] - Returns entries for the last number of days
devices - [optional] - Comma separated list of devices to get data. Can be a single device
resident - [optional] - ID of resident to limit data to

Results

SUCCESS, the total number of readings, and a list readings.

xml

<gcapi>
	<result>SUCCESS</result>
	<bp>
		<timestamp>05/12/12 09:35:44</timestamp>
		<deviceId>1001</deviceId>
		<residentId>cf6ff892-3124-41ef-8c77-e729f0f66fc5</residentId>
		<systolic>138</systolic>
		<diastolic>88</diastolic>
		<pulse>49</pulse>
		<mean-ap>108</mean-ap>
	</bp>
	<bp>
		<timestamp>05/11/12 07:11:08</timestamp>
		<deviceId>1001</deviceId>
		<residentId>cf6ff892-3124-41ef-8c77-e729f0f66fc5</residentId>
		<systolic>128</systolic>
		<diastolic>84</diastolic>
		<pulse>58</pulse>
		<mean-ap>98</mean-ap>
	</bp>
	<totalEntries>2</totalEntries>
</gcapi>

json

{
   "gcapi": {
       "result": "SUCCESS",
       "bp": [
           {
               "timestamp": "07/31/12 08:15:57",
               "deviceId": "1001",
               "residentId": "cf6ff892-3124-41ef-8c77-e729f0f66fc5",
               "systolic": "134",
               "diastolic": "95",
               "pulse": "54",
               "mean-ap": "117"
           },
           {
               "timestamp": "07/28/12 07:51:16",
               "deviceId": "1001",
               "residentId": "cf6ff892-3124-41ef-8c77-e729f0f66fc5",
               "systolic": "134",
               "diastolic": "89",
               "pulse": "51",
               "mean-ap": "104"
           }
       ],
       "totalEntries": "2"
   }
}

weight

Fetches scale history from the system

Parameters

limit - [optional] - Limits the number of entries returned. Defaults to 50
offset - [optional] - Skip this number of entries. Useful for paging
date - [optional] - Returns only entries for this date
days - [optional] - Returns entries for the last number of days
devices - [optional] - Comma separated list of devices to get data. Can be a single device
resident - [optional] - ID of resident to limit data to

Results

SUCCESS, the total number of readings, and a list readings.

xml

<gcapi>
	<result>SUCCESS</result>
	<weight>
		<timestamp>05/16/12 07:30:26</timestamp>
		<deviceId>1000</deviceId>
		<residentId>cf6ff892-3124-41ef-8c77-e729f0f66fc5</residentId>
		<value>179.6</value>
	</weight>
	<weight>
		<timestamp>05/15/12 08:00:52</timestamp>
		<deviceId>1000</deviceId>
		<residentId>cf6ff892-3124-41ef-8c77-e729f0f66fc5</residentId>
		<value>179.8</value>
	</weight>
	<totalEntries>1354</totalEntries>
</gcapi>

json

{
   "gcapi": {
       "result": "SUCCESS",
       "weight": [
           {
               "timestamp": "07/31/12 08:14:45",
               "deviceId": "1000",
               "residentId": "cf6ff892-3124-41ef-8c77-e729f0f66fc5",
               "value": "176.6"
           },
           {
               "timestamp": "07/28/12 07:49:32",
               "deviceId": "1000",
               "residentId": "cf6ff892-3124-41ef-8c77-e729f0f66fc5",
               "value": "176.2"
           }
       ],
       "totalEntries": "2"
   }
}

temp

Fetches temperature sensor history from the system

Parameters

limit - [optional] - Limits the number of entries returned. Defaults to 50
offset - [optional] - Skip this number of entries. Useful for paging
date - [optional] - Returns only entries for this date
days - [optional] - Returns entries for the last number of days
devices - [optional] - Comma separated list of devices to get data. Can be a single device

Results

SUCCESS, the total number of readings, and a list readings.

xml

<gcapi>
	<result>SUCCESS</result>
	<temp>
		<timestamp>09/14/10 02:50:29</timestamp>
		<deviceId>1070</deviceId>
		<value>70</value>
	</temp>
	<temp>
		<timestamp>09/14/10 01:37:27</timestamp>
		<deviceId>1070</deviceId>
		<value>71</value>
	</temp>
	<totalEntries>2</totalEntries>
</gcapi>

json

{
   "gcapi": {
       "result": "SUCCESS",
       "temp": [
           {
               "timestamp": "07/20/12 12:06:18",
               "deviceId": "103",
               "value": "73"
           },
           {
               "timestamp": "07/20/12 11:53:14",
               "deviceId": "103",
               "value": "74"
           }
       ],
       "totalEntries": "2"
   }
}

bed

Fetches bed sensor history from the system

Parameters

limit - [optional] - Limits the number of entries returned. Defaults to 50
offset - [optional] - Skip this number of entries. Useful for paging
date - [optional] - Returns only entries for this date
days - [optional] - Returns entries for the last number of days
devices - [optional] - Comma separated list of devices to get data. Can be a single device

Results

SUCCESS, the total number of readings, and a list readings.

xml

<gcapi>
	<result>SUCCESS</result>
	<totalEntries>1</totalEntries>
	<bed>
		<timestamp>...</timestamp>
		<device-id>...</device-id>
		<value>[Occupied|Unoccupied]</value>
	</bed>
</gcapi>

json

{
   "gcapi": {
       "result": "SUCCESS",
       "bed": [{
               "timestamp": "...",
               "device-id": "...",
               "value": "[Occupied|Unoccupied]"
       }],
       "totalEntries": "1"
   }
}

oxi

Fetches oximeter history from the system

Parameters

limit - [optional] - Limits the number of entries returned. Defaults to 50
offset - [optional] - Skip this number of entries. Useful for paging
date - [optional] - Returns only entries for this date
days - [optional] - Returns entries for the last number of days
devices - [optional] - Comma separated list of devices to get data. Can be a single device
resident - [optional] - ID of resident to limit data to

Results

SUCCESS, the total number of readings, and a list readings.

xml

<gcapi>
	<result>SUCCESS</result>
	<oxi>
		<timestamp>05/06/12 16:55:57</timestamp>
		<deviceId>1003</deviceId>
		<residentId>b61790c5-0f61-40a7-864b-87b8c62cc750</residentId>
		<spo2>97</spo2>
		<pulse>72</pulse>
	</oxi>
	<oxi>
		<timestamp>05/05/12 22:34:57</timestamp>
		<deviceId>1003</deviceId>
		<residentId>b61790c5-0f61-40a7-864b-87b8c62cc750</residentId>
		<spo2>99</spo2>
		<pulse>83</pulse>
	</oxi>
	<totalEntries>2</totalEntries>
</gcapi>

json

{
   "gcapi": {
       "result": "SUCCESS",
       "oxi": [
           {
               "timestamp": "08/01/12 08:11:59",
               "deviceId": "1003",
               "residentId": "b61790c5-0f61-40a7-864b-87b8c62cc750",
               "spo2": "96",
               "pulse": "63"
           },
           {
               "timestamp": "07/31/12 10:19:25",
               "deviceId": "1003",
               "residentId": "b61790c5-0f61-40a7-864b-87b8c62cc750",
               "spo2": "95",
               "pulse": "63"
           }
       ],
       "totalEntries": "2"
   }
}

motion

Fetches motion sensor history from the system

Parameters

limit - [optional] - Limits the number of entries returned. Defaults to 50
offset - [optional] - Skip this number of entries. Useful for paging
date - [optional] - Returns only entries for this date
days - [optional] - Returns entries for the last number of days
devices - [optional] - Comma separated list of devices to get data. Can be a single device

Results

SUCCESS, the total number of readings, and a list readings.

xml

<gcapi>

<result>SUCCESS</result> <motion> <timestamp>07/20/12 14:07:36</timestamp> <deviceId>105</deviceId> <value>Off</value> </motion> <motion> <timestamp>07/20/12 14:05:48</timestamp> <deviceId>102</deviceId> <value>Off</value> </motion> <totalEntries>55</totalEntries>

</gcapi>

json

{
   "gcapi": {
       "result": "SUCCESS",
       "motion": [
           {
               "timestamp": "07/20/12 14:07:36",
               "deviceId": "105",
               "value": "Off"
           },
           {
               "timestamp": "07/20/12 14:05:48",
               "deviceId": "102",
               "value": "Off"
           }
       ],
       "totalEntries": "2"
   }
}

gluc

Fetches glucometer history from the system

Parameters

limit - [optional] - Limits the number of entries returned. Defaults to 50
offset - [optional] - Skip this number of entries. Useful for paging
date - [optional] - Returns only entries for this date
days - [optional] - Returns entries for the last number of days
devices - [optional] - Comma separated list of devices to get data. Can be a single device
resident - [optional] - ID of resident to limit data to

Results

SUCCESS, the total number of readings, and a list readings.

xml

<gcapi>

<result>SUCCESS</result> <gluc> <timestamp>08/01/12 07:24:00</timestamp> <deviceId>1002</deviceId> <residentId>b61790c5-0f61-40a7-864b-87b8c62cc750</residentId> <value>113</value> <notes></notes> </gluc> <gluc> <timestamp>07/31/12 08:17:00</timestamp> <deviceId>1002</deviceId> <residentId>b61790c5-0f61-40a7-864b-87b8c62cc750</residentId> <value>105</value> <notes></notes> </gluc> <totalEntries>2</totalEntries>

</gcapi>

json

{
   "gcapi": {
       "result": "SUCCESS",
       "gluc": [
           {
               "timestamp": "08/01/12 07:24:00",
               "deviceId": "1002",
               "residentId": "b61790c5-0f61-40a7-864b-87b8c62cc750",
               "value": "113",
               "notes": ""
           },
           {
               "timestamp": "07/31/12 08:17:00",
               "deviceId": "1002",
               "residentId": "b61790c5-0f61-40a7-864b-87b8c62cc750",
               "value": "105",
               "notes": ""
           }
       ],
       "totalEntries": "2"
   }
}

door

Fetches door sensor history from the system

Parameters

limit - [optional] - Limits the number of entries returned. Defaults to 50
offset - [optional] - Skip this number of entries. Useful for paging
date - [optional] - Returns only entries for this date
days - [optional] - Returns entries for the last number of days
devices - [optional] - Comma separated list of devices to get data. Can be a single device

Results

SUCCESS, the total number of readings, and a list readings.

xml

<gcapi>

<result>SUCCESS</result> <door> <timestamp>08/01/12 07:24:00</timestamp> <deviceId>1002</deviceId> <value>Open</value> </door> <door> <timestamp>07/31/12 08:17:00</timestamp> <deviceId>1002</deviceId> <value>Closed</value> </door> <totalEntries>2</totalEntries>

</gcapi>

json

{
   "gcapi": {
       "result": "SUCCESS",
       "door": [
           {
               "timestamp": "08/01/12 07:24:00",
               "deviceId": "1002",
               "value": "Open"
           },
           {
               "timestamp": "07/31/12 08:17:00",
               "deviceId": "1002",
               "value": "Closed"
           }
       ],
       "totalEntries": "2"
   }
}

Assign API

URL: $SystemAddress/api/assign.php

Caregiver API

URL: $SystemAddress/api/caregiver.php

Care note API

URL: $SystemAddress/api/carenote.php

Configure API

URL: $SystemAddress/api/configure.php

Device API

URL: $SystemAddress/api/device.php

Log API

URL: $SystemAddress/api/log.php

Media API

URL: $SystemAddress/api/media.php

Medication API

URL: $SystemAddress/api/medication.php

Message API

URL: $SystemAddress/api/message.php

PIN API

URL: $SystemAddress/api/pin.php

Resident API

URL: $SystemAddress/api/resident.php

Rule API

URL: $SystemAddress/api/rule.php

System API

URL: $SystemAddress/api/system.php

Other Resources

Experimental JavaScript library

Difference between revisions of "Internal GCAPI"

Revision as of 19:42, 2 August 2012

Calling GCAPI

Local Application Authentication

Results From GCAPI

XML Results

JSON Results

API Subsystems

History

bp

Parameters

Results

xml

json

weight

Parameters

Results

xml

json

temp

Parameters

Results

xml

json

bed

Parameters

Results

xml

json

oxi

Parameters

Results

xml

json

motion

Parameters

Results

xml

json

gluc

Parameters

Results

xml

json

door

Parameters

Results

xml

json

Assign API

Caregiver API

Care note API

Configure API

Device API

Log API

Media API

Medication API

Message API

PIN API

Resident API

Rule API

System API

Other Resources

Navigation menu

Search