{"_id":"59e70b9ee027ae002e7d2ee7","category":{"_id":"59e70b9ee027ae002e7d2ed6","version":"59e70b9ee027ae002e7d2ed2","project":"5496d393f52a630b00519cdd","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2014-12-21T18:05:46.941Z","from_sync":false,"order":3,"slug":"rest-api","title":"REST API"},"parentDoc":null,"user":"5496d353f52a630b00519cdc","project":"5496d393f52a630b00519cdd","version":{"_id":"59e70b9ee027ae002e7d2ed2","project":"5496d393f52a630b00519cdd","__v":2,"createdAt":"2017-10-18T08:06:54.462Z","releaseDate":"2017-10-18T08:06:54.462Z","categories":["59e70b9ee027ae002e7d2ed3","59e70b9ee027ae002e7d2ed4","59e70b9ee027ae002e7d2ed5","59e70b9ee027ae002e7d2ed6","59e70b9ee027ae002e7d2ed7","59e70b9ee027ae002e7d2ed8","59e70b9ee027ae002e7d2ed9","59e70b9ee027ae002e7d2eda","59e70b9ee027ae002e7d2edb","59e70b9ee027ae002e7d2edc","59e70b9ee027ae002e7d2edd","59e70b9ee027ae002e7d2ede","59e70b9ee027ae002e7d2edf","5b8661ccdd19310003a3fa0b"],"is_deprecated":false,"is_hidden":false,"is_beta":true,"is_stable":true,"codename":"","version_clean":"2.0.10","version":"2.0.10"},"githubsync":"","__v":0,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2014-12-21T18:11:18.776Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":0,"body":"[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"REST API Basics\"\n}\n[/block]\n##Request Structure\n\nThe base URL of the production server is: https://api.placer.io.\nEach request to the server should be constructed with the base URL followed by a path to a resource, query parameters and authentication parameters comprising a timestamp and signature.\nRequests are performed using HTTP GET method.\n\n**Request example** \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"https://api.placer.io/v2/apps/2324123/3users4?limit=105&timestamp=1261496500&signature=abcdef01234567896\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\nRequest elements description:\n\n1)* **https://api.placer.io*** - Production server BASE_URL\n\n2) ***v2/apps/ ***- API version (2) and the apps resource. All queries in this document are done using this path.\n\n3) ***324123/*** - Path to specific application data being queried. Your Placer’s App_Key goes here.\n\n4) ***users***- The resource being queried. “Users” in this example. \n\n5) ***limit=10*** - Query parameter to limit the returned result to 10 items.\n\n6)*** timestamp=1261496500&signature=abcdef0123456789***- timestamp and signature are part of Placer’s authentication process. Please see [Authentication](doc:server-2-server-rest-api) for implementation instructions.\n\n\n##Response Structure\nQuery results are returned in a JSON format (‘application/json’).\n\nThe JSON response data contains an attribute called “result” with a “*SUCCESS*” or “*FAILURE*” value to mark the query success. \n\nSuccessful queries will contain an additional “*data*” attribute containing a JSON Array with the results for the API call and “*total_count*” attribute containing the number of results that matched the query. “*total_count*” is used for paging the query results and fetching more data.\nFailed queries will contain “*error*” and “*error_code*”, successful queries contains “*error_code*” with a value “*0*”.\n\n**Example [Insights](doc:user-insights) Response:** \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"data\\\": [\\n        {\\n            \\\"insights\\\": {\\n             // INSIGHTS GOES HERE\\n            },\\n            \\\"device_id\\\": \\\"57336937fdef2648247f69d9\\\" \\n        }\\n    ], \\n    \\\"error_code\\\": 0, \\n    \\\"result\\\": \\\"SUCCESS\\\", \\n    \\\"total_count\\\": 1\\n}\",\n      \"language\": \"json\",\n      \"name\": null\n    }\n  ]\n}\n[/block]\nList of errors, codes, their meaning and the request HTTP Status:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Http Status\",\n    \"h-1\": \"error_ code\",\n    \"h-2\": \"error\",\n    \"h-3\": \"Meaning\",\n    \"0-3\": \"General Authentication failure error. App_key unknown.\",\n    \"0-2\": \"AUTHENTICATION_FAILED\",\n    \"0-1\": \"1000\",\n    \"0-0\": \"500\",\n    \"1-0\": \"500\",\n    \"1-1\": \"1004\",\n    \"1-2\": \"MISSING_AUTH_TOKEN\",\n    \"1-3\": \"Missing app_key\",\n    \"2-0\": \"500\",\n    \"2-1\": \"1005\",\n    \"3-1\": \"1007\",\n    \"4-1\": \"2002\",\n    \"5-1\": \"5000\",\n    \"6-1\": \"6002\",\n    \"3-0\": \"500\",\n    \"4-0\": \"500\",\n    \"5-0\": \"500\",\n    \"6-0\": \"500\",\n    \"2-2\": \"INVALID_TIME_STAMP\",\n    \"6-2\": \"API_NOT_SUPPORTED\",\n    \"5-2\": \"GENERAL_ERROR\",\n    \"4-2\": \"INVALID_ARGUMENTS\",\n    \"3-2\": \"INVALID_SIGNATURE\",\n    \"2-3\": \"Missing or provided timestamp is not up to date\",\n    \"6-3\": \"Unknown API Endpoint\",\n    \"5-3\": \"Unknown error\",\n    \"4-3\": \"Invalid query parameters\",\n    \"3-3\": \"Generated Signature is invalid. App_secret may be invalid\"\n  },\n  \"cols\": 4,\n  \"rows\": 7\n}\n[/block]","excerpt":"*Implementing the Server-to-Server API will allow you to fully utilize the capabilities of Placer’s insights in your application and service. \nThis section describes the server API endpoints, query parameters and response structure.*","slug":"overview","type":"basic","title":"Overview"}

Overview

*Implementing the Server-to-Server API will allow you to fully utilize the capabilities of Placer’s insights in your application and service. This section describes the server API endpoints, query parameters and response structure.*

[block:api-header] { "type": "basic", "title": "REST API Basics" } [/block] ##Request Structure The base URL of the production server is: https://api.placer.io. Each request to the server should be constructed with the base URL followed by a path to a resource, query parameters and authentication parameters comprising a timestamp and signature. Requests are performed using HTTP GET method. **Request example** [block:code] { "codes": [ { "code": "https://api.placer.io/v2/apps/2324123/3users4?limit=105&timestamp=1261496500&signature=abcdef01234567896", "language": "curl" } ] } [/block] Request elements description: 1)* **https://api.placer.io*** - Production server BASE_URL 2) ***v2/apps/ ***- API version (2) and the apps resource. All queries in this document are done using this path. 3) ***324123/*** - Path to specific application data being queried. Your Placer’s App_Key goes here. 4) ***users***- The resource being queried. “Users” in this example. 5) ***limit=10*** - Query parameter to limit the returned result to 10 items. 6)*** timestamp=1261496500&signature=abcdef0123456789***- timestamp and signature are part of Placer’s authentication process. Please see [Authentication](doc:server-2-server-rest-api) for implementation instructions. ##Response Structure Query results are returned in a JSON format (‘application/json’). The JSON response data contains an attribute called “result” with a “*SUCCESS*” or “*FAILURE*” value to mark the query success. Successful queries will contain an additional “*data*” attribute containing a JSON Array with the results for the API call and “*total_count*” attribute containing the number of results that matched the query. “*total_count*” is used for paging the query results and fetching more data. Failed queries will contain “*error*” and “*error_code*”, successful queries contains “*error_code*” with a value “*0*”. **Example [Insights](doc:user-insights) Response:** [block:code] { "codes": [ { "code": "{\n \"data\": [\n {\n \"insights\": {\n // INSIGHTS GOES HERE\n },\n \"device_id\": \"57336937fdef2648247f69d9\" \n }\n ], \n \"error_code\": 0, \n \"result\": \"SUCCESS\", \n \"total_count\": 1\n}", "language": "json", "name": null } ] } [/block] List of errors, codes, their meaning and the request HTTP Status: [block:parameters] { "data": { "h-0": "Http Status", "h-1": "error_ code", "h-2": "error", "h-3": "Meaning", "0-3": "General Authentication failure error. App_key unknown.", "0-2": "AUTHENTICATION_FAILED", "0-1": "1000", "0-0": "500", "1-0": "500", "1-1": "1004", "1-2": "MISSING_AUTH_TOKEN", "1-3": "Missing app_key", "2-0": "500", "2-1": "1005", "3-1": "1007", "4-1": "2002", "5-1": "5000", "6-1": "6002", "3-0": "500", "4-0": "500", "5-0": "500", "6-0": "500", "2-2": "INVALID_TIME_STAMP", "6-2": "API_NOT_SUPPORTED", "5-2": "GENERAL_ERROR", "4-2": "INVALID_ARGUMENTS", "3-2": "INVALID_SIGNATURE", "2-3": "Missing or provided timestamp is not up to date", "6-3": "Unknown API Endpoint", "5-3": "Unknown error", "4-3": "Invalid query parameters", "3-3": "Generated Signature is invalid. App_secret may be invalid" }, "cols": 4, "rows": 7 } [/block]