{"__v":3,"_id":"564d1afb4567342100ad96bc","category":{"__v":1,"_id":"564d1af94567342100ad96ae","pages":["564d1afb4567342100ad96bb","564d1afb4567342100ad96bc","564d1afb4567342100ad96bd","564d1afb4567342100ad96be","564d1afb4567342100ad96bf"],"project":"551375e1d04af219007ddc52","version":"564d1af84567342100ad96aa","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-03-27T02:56:56.435Z","from_sync":false,"order":3,"slug":"data-retrieval","title":"Data Retrieval"},"project":"551375e1d04af219007ddc52","user":"551375a3d04af219007ddc50","version":{"__v":1,"_id":"564d1af84567342100ad96aa","project":"551375e1d04af219007ddc52","createdAt":"2015-11-19T00:42:32.705Z","releaseDate":"2015-11-19T00:42:32.705Z","categories":["564d1af94567342100ad96ab","564d1af94567342100ad96ac","564d1af94567342100ad96ad","564d1af94567342100ad96ae","564d1af94567342100ad96af","564d1af94567342100ad96b0","564d1af94567342100ad96b1","564d1af94567342100ad96b2"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.1.0","version":"1.1"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-03-27T02:58:13.119Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":1,"body":"#Example Queries\n\nHuman API lets you query a user's health data with an `access_token` query parameter or a `Bearer` token authorization header. For details on how to authorize users and retrieve these tokens please click [here](doc:integrating-human-connect).\n\nQuery Parameter:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl https://api.humanapi.co/v1/human?access_token=demo\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\nBearer token:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -H \\\"Authorization: Bearer demo\\\" https://api.humanapi.co/v1/human\\n\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"The `demo` access token will serve [demo user data](doc:demo-data). Replace it with a valid `accessToken` to get data for that specific user.\"\n}\n[/block]\n\n#Media Types\nHuman API uses JSON (JavaScript Object Notation) for all payloads. To accommodate for this:\n\n- Set the **Accept Header** to `application/json` when querying data.\n- Set the **Content-Type Header** to `application/json` when sending data.\n\n\n#API Versions\nDifferent versions of Human API can be used by specifying the version number in the url, i.e.` /v1`:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"https://api.humanapi.co/[version]/human\\nhttps://api.humanapi.co/v1/human\",\n      \"language\": \"http\"\n    }\n  ]\n}\n[/block]\nThe most current version of Human API is **v1**\n\n\n#Query Options \nThe standard query options for Human API are as described in the table below. These parameters make it easier for you to implement smart synchronization for your application. For instance, by using the `updated_since` parameter you only retrieve the data that was changed or added since the specified time.\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Parameter\",\n    \"h-1\": \"Description\",\n    \"0-0\": \"`limit`\",\n    \"0-1\": \"The max number of records to return in one query. \\n*Default is 50. Maximum is 500 if set.*\",\n    \"1-0\": \"`offset`\",\n    \"1-1\": \"The index of the first record to return. *Default is 0*\",\n    \"2-0\": \"`created_since`\",\n    \"2-1\": \"Returns records that are created after the specified date.\",\n    \"3-0\": \"`updated_since`\",\n    \"3-1\": \"Returns records that are updated after the specified date.\",\n    \"4-0\": \"`created_before`\",\n    \"4-1\": \"Returns records that are created before the specified date.\",\n    \"5-0\": \"`updated_before`\",\n    \"5-1\": \"Returns records that are updated before the specified date.\",\n    \"6-0\": \"`source`\",\n    \"6-1\": \"Returns filtered data from a specific source.\\n\\n(Use the source name, all lowercase no spaces as found on records. \\ne.g. - `googlefit`, `ihealth`, `myfitnesspal`, etc.)\"\n  },\n  \"cols\": 2,\n  \"rows\": 7\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"All dates are in UTC date format:  YYYYMMDDTHHmmssZ\",\n  \"title\": \"\"\n}\n[/block]\n#Date Ranges\nIn addition to the parameters listed above, you can also query by a date range. These parameters must be used together.\n[block:parameters]\n{\n  \"data\": {\n    \"0-2\": \"The oldest date to retrieve. \\n*Format YYYY-MM-DD*\",\n    \"0-0\": \"`start_date`\",\n    \"1-0\": \"`end_date`\",\n    \"0-1\": \"The oldest date to retrieve. \\n*Format YYYY-MM-DD*\",\n    \"1-1\": \"The most recent date to retrieve. \\n*Format YYYY-MM-DD*\",\n    \"h-0\": \"Parameter\",\n    \"h-1\": \"Description\"\n  },\n  \"cols\": 2,\n  \"rows\": 2\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Data Types\"\n}\n[/block]\n#Discrete Measurements\nA discrete measurement is a unit of data that is captured at a point in time and has a timestamp, a value, and a type. A measurement can also have an optional location or other meta data. To retrieve the discrete measurements you can follow the following pattern:\n\n\nTo retrieve the latest reading:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"/v1/human/[type]\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\n\nTo retrieve a reading by ID:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"/v1/human/[type]/{id}\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\n\nTo retrieve the list of readings:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"/v1/human/[type]/readings\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\n\nTo retrieve a list of readings for a specific date:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"/v1/human/[type]/readings/daily/{YYYY-MM-DD}\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\n\n#Periodic Data\nPeriodic data, unlike discrete data, always has a start and end date. The data types that fall into this category are **activities**, **sleeps**, and **locations**. This type of data can be retrieved as a list of objects or as a summary object for a specific date or time period.\n\n\nTo retrieve a list of periodic data objects:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"/v1/human/[type]\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\n\nTo retrieve a single object by ID:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"/v1/human/[type]/{id}\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\n\nTo retrieve a list of objects for a specific date:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"/v1/human/[type]/daily/{YYYY-MM-DD}\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\n\nTo retrieve the latest summary objects:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"/v1/human/[type]/summaries\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\n\nTo retrieve a summary object for a specific date:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"/v1/human/[type]/summaries/{YYYY-MM-DD}\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\n\nTo retrieve a summary object by Id:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"/v1/human/[type]/summaries/{id}\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\n#Medical Data\nMedical data includes any data from the [Medical API endpoints](https://reference.humanapi.co/#medical-apis).\n\nTo retrieve a list of periodic data objects:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"/v1/human/[type]\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\nTo retrieve a single object by ID:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"/v1/human/[type]/{id}\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Pagination Conventions\"\n}\n[/block]\nTo make it easier to retrieve all the data for a user you can iterate through their historical data using the `Link Header` and, optionally, the `X-Total-Count Header`. The Link Header contains the first, prev, next, and last links that will help you easily iterate through all the records available for a query. The Link Header follows the [RFC5988 standard](http://tools.ietf.org/html/rfc5988).\n\n\nFor example, if you query a user with the following parameters:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"/activities?start_date=2013-01-01&limit=50&offset=100\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\n\nYour response headers would return like this:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"Link:   https://api.humanapi.co/v1/human/activities?&limit=50&start_date=2013-01-01&offset=50; \\nrel=\\\"prev\\\",\\n   https://api.humanapi.co/v1/human/activities?limit=50&start_date=2013-01-01&offset=8450; \\nrel=\\\"last\\\",\\n   https://api.humanapi.co/v1/human/activities?limit=50&start_date=2013-01-01&offset=0; \\nrel=\\\"first\\\"\",\n      \"language\": \"http\"\n    }\n  ]\n}\n[/block]\n\nThere is also a total count for the query stored in the X-Total-Count Header:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"X-Total-Count: 8490\",\n      \"language\": \"http\"\n    }\n  ]\n}\n[/block]","excerpt":"Conventions to follow when working with Human API","slug":"patterns-and-conventions-reference","type":"basic","title":"Patterns and Conventions"}

Patterns and Conventions

Conventions to follow when working with Human API

#Example Queries Human API lets you query a user's health data with an `access_token` query parameter or a `Bearer` token authorization header. For details on how to authorize users and retrieve these tokens please click [here](doc:integrating-human-connect). Query Parameter: [block:code] { "codes": [ { "code": "curl https://api.humanapi.co/v1/human?access_token=demo", "language": "curl" } ] } [/block] Bearer token: [block:code] { "codes": [ { "code": "curl -H \"Authorization: Bearer demo\" https://api.humanapi.co/v1/human\n", "language": "curl" } ] } [/block] [block:callout] { "type": "info", "body": "The `demo` access token will serve [demo user data](doc:demo-data). Replace it with a valid `accessToken` to get data for that specific user." } [/block] #Media Types Human API uses JSON (JavaScript Object Notation) for all payloads. To accommodate for this: - Set the **Accept Header** to `application/json` when querying data. - Set the **Content-Type Header** to `application/json` when sending data. #API Versions Different versions of Human API can be used by specifying the version number in the url, i.e.` /v1`: [block:code] { "codes": [ { "code": "https://api.humanapi.co/[version]/human\nhttps://api.humanapi.co/v1/human", "language": "http" } ] } [/block] The most current version of Human API is **v1** #Query Options The standard query options for Human API are as described in the table below. These parameters make it easier for you to implement smart synchronization for your application. For instance, by using the `updated_since` parameter you only retrieve the data that was changed or added since the specified time. [block:parameters] { "data": { "h-0": "Parameter", "h-1": "Description", "0-0": "`limit`", "0-1": "The max number of records to return in one query. \n*Default is 50. Maximum is 500 if set.*", "1-0": "`offset`", "1-1": "The index of the first record to return. *Default is 0*", "2-0": "`created_since`", "2-1": "Returns records that are created after the specified date.", "3-0": "`updated_since`", "3-1": "Returns records that are updated after the specified date.", "4-0": "`created_before`", "4-1": "Returns records that are created before the specified date.", "5-0": "`updated_before`", "5-1": "Returns records that are updated before the specified date.", "6-0": "`source`", "6-1": "Returns filtered data from a specific source.\n\n(Use the source name, all lowercase no spaces as found on records. \ne.g. - `googlefit`, `ihealth`, `myfitnesspal`, etc.)" }, "cols": 2, "rows": 7 } [/block] [block:callout] { "type": "info", "body": "All dates are in UTC date format: YYYYMMDDTHHmmssZ", "title": "" } [/block] #Date Ranges In addition to the parameters listed above, you can also query by a date range. These parameters must be used together. [block:parameters] { "data": { "0-2": "The oldest date to retrieve. \n*Format YYYY-MM-DD*", "0-0": "`start_date`", "1-0": "`end_date`", "0-1": "The oldest date to retrieve. \n*Format YYYY-MM-DD*", "1-1": "The most recent date to retrieve. \n*Format YYYY-MM-DD*", "h-0": "Parameter", "h-1": "Description" }, "cols": 2, "rows": 2 } [/block] [block:api-header] { "type": "basic", "title": "Data Types" } [/block] #Discrete Measurements A discrete measurement is a unit of data that is captured at a point in time and has a timestamp, a value, and a type. A measurement can also have an optional location or other meta data. To retrieve the discrete measurements you can follow the following pattern: To retrieve the latest reading: [block:code] { "codes": [ { "code": "/v1/human/[type]", "language": "text" } ] } [/block] To retrieve a reading by ID: [block:code] { "codes": [ { "code": "/v1/human/[type]/{id}", "language": "text" } ] } [/block] To retrieve the list of readings: [block:code] { "codes": [ { "code": "/v1/human/[type]/readings", "language": "text" } ] } [/block] To retrieve a list of readings for a specific date: [block:code] { "codes": [ { "code": "/v1/human/[type]/readings/daily/{YYYY-MM-DD}", "language": "text" } ] } [/block] #Periodic Data Periodic data, unlike discrete data, always has a start and end date. The data types that fall into this category are **activities**, **sleeps**, and **locations**. This type of data can be retrieved as a list of objects or as a summary object for a specific date or time period. To retrieve a list of periodic data objects: [block:code] { "codes": [ { "code": "/v1/human/[type]", "language": "text" } ] } [/block] To retrieve a single object by ID: [block:code] { "codes": [ { "code": "/v1/human/[type]/{id}", "language": "text" } ] } [/block] To retrieve a list of objects for a specific date: [block:code] { "codes": [ { "code": "/v1/human/[type]/daily/{YYYY-MM-DD}", "language": "text" } ] } [/block] To retrieve the latest summary objects: [block:code] { "codes": [ { "code": "/v1/human/[type]/summaries", "language": "text" } ] } [/block] To retrieve a summary object for a specific date: [block:code] { "codes": [ { "code": "/v1/human/[type]/summaries/{YYYY-MM-DD}", "language": "text" } ] } [/block] To retrieve a summary object by Id: [block:code] { "codes": [ { "code": "/v1/human/[type]/summaries/{id}", "language": "text" } ] } [/block] #Medical Data Medical data includes any data from the [Medical API endpoints](https://reference.humanapi.co/#medical-apis). To retrieve a list of periodic data objects: [block:code] { "codes": [ { "code": "/v1/human/[type]", "language": "text" } ] } [/block] To retrieve a single object by ID: [block:code] { "codes": [ { "code": "/v1/human/[type]/{id}", "language": "text" } ] } [/block] [block:api-header] { "type": "basic", "title": "Pagination Conventions" } [/block] To make it easier to retrieve all the data for a user you can iterate through their historical data using the `Link Header` and, optionally, the `X-Total-Count Header`. The Link Header contains the first, prev, next, and last links that will help you easily iterate through all the records available for a query. The Link Header follows the [RFC5988 standard](http://tools.ietf.org/html/rfc5988). For example, if you query a user with the following parameters: [block:code] { "codes": [ { "code": "/activities?start_date=2013-01-01&limit=50&offset=100", "language": "text" } ] } [/block] Your response headers would return like this: [block:code] { "codes": [ { "code": "Link: https://api.humanapi.co/v1/human/activities?&limit=50&start_date=2013-01-01&offset=50; \nrel=\"prev\",\n https://api.humanapi.co/v1/human/activities?limit=50&start_date=2013-01-01&offset=8450; \nrel=\"last\",\n https://api.humanapi.co/v1/human/activities?limit=50&start_date=2013-01-01&offset=0; \nrel=\"first\"", "language": "http" } ] } [/block] There is also a total count for the query stored in the X-Total-Count Header: [block:code] { "codes": [ { "code": "X-Total-Count: 8490", "language": "http" } ] } [/block]