{"_id":"59e70b9ee027ae002e7d2ee6","category":{"_id":"5b8661ccdd19310003a3fa0b","project":"5496d393f52a630b00519cdd","version":"59e70b9ee027ae002e7d2ed2","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2018-08-29T09:05:16.970Z","from_sync":false,"order":6,"slug":"venue-detection","title":"Venue Detection"},"project":"5496d393f52a630b00519cdd","user":"5496d353f52a630b00519cdc","parentDoc":null,"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":"2017-03-07T09:14:16.926Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"settings":"","results":{"codes":[]},"auth":"required","params":[],"url":""},"isReference":false,"order":0,"body":"Use Placer's Near-Real-Time Venue Detection API (VD-API) to identify venues currently being visited by your mobile users.\nThe VD-API resolves location coordinates, Wi-Fi and beacon scans, collected by your mobile app/SDK to venue details, in near-real-time.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Before you start\",\n  \"body\": \"Contact your Placer account manager for your 'VD-API URL', App-Key and App-Secret. \\nAlso, let us know if you are interested in trigger (postback URL) response, a synchronous response or bucket export (see explanation below).\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"How it works\"\n}\n[/block]\n##Request\nSend a VD-Request to Placer's VD-API URL of one of the following types:\n  * [Structured Visits (visits with start/end time)](#vd-request-structured-visits) \n  * [Unstructured Visits (visits without start/end time)](#vd-request-unstructured-visits) \n\n##Response\nResults can be provided in either one of the following methods. Please contact your account manager to configure the desired solution:\n  * **Server Side Trigger** - For each visit, Placer will generate a [VD-Trigger-Response](#vd-trigger-response-structure) with the venue name, category and additional details. Triggers will be sent to your server's postback URL within 1 minute.\n  * **Bucket Export** - For each visit, Placer will generate a [VD-Trigger-Response](#vd-trigger-response-structure) that will be exported to your AWS/GCS bucket (see [Data Export](doc:data-export)).\n  * **A synchronous response** - generates an immediate [VD-Synchronous Response](#vd-synchronous-response-structure) response with the results.\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"- Placer uses a hash-based message authentication code (HMAC) for server to server queries. Each request should include a **timestamp** and **signature**, as described in the [Authentication](doc:server-2-server-rest-api) section. \\n- Request content should be compressed using gzip with the following http header - **Content-Encoding: gzip**\",\n  \"title\": \"Note\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"VD-Request - Structured Visits\"\n}\n[/block]\nUse this format if your request includes visit start/end time or multiple events.\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Field\",\n    \"h-1\": \"Description\",\n    \"h-2\": \"Type\",\n    \"h-3\": \"Example\",\n    \"6-0\": \"os\\n*(optional)*\",\n    \"8-0\": \"device_model\\n*(optional)*\",\n    \"7-0\": \"os_version\\n*(optional)*\",\n    \"7-1\": \"OS version.\",\n    \"8-1\": \"The device model.\",\n    \"6-1\": \"The device operating system: Android or iOS.\",\n    \"6-2\": \"String\",\n    \"7-2\": \"String\",\n    \"8-2\": \"String\",\n    \"8-3\": \"LG-D802\",\n    \"7-3\": \"4.4.2\",\n    \"6-3\": \"Android\",\n    \"9-0\": \"device_brand\\n*(optional)*\",\n    \"9-1\": \"The device brand.\",\n    \"9-2\": \"String\",\n    \"9-3\": \"LGE\",\n    \"2-0\": \"user_id\\n*(optional)*\",\n    \"2-1\": \"Should be used if advertising ID is not available. If both User ID and Advertising ID are provided, Placer will ignore the User ID.\",\n    \"2-2\": \"String\",\n    \"2-3\": \"56c18475ff021108d127cda8\",\n    \"10-0\": \"gender\\n*(optional)*\",\n    \"11-0\": \"yob\\n*(optional)*\",\n    \"10-1\": \"Gender: “M” male, “F” female, “O” Other.\",\n    \"11-1\": \"Year of birth as a 4-digit integer\",\n    \"11-2\": \"int\",\n    \"11-3\": \"1984\",\n    \"10-2\": \"String\",\n    \"10-3\": \"M\",\n    \"12-0\": \"custom_data\\n*(optional)*\",\n    \"12-1\": \"Developers can define custom data and attributes for each device. This data will be returned in the [Device Details Structure](doc:device-details).\",\n    \"12-2\": \"JSON\",\n    \"12-3\": \"{“number_of_family_members”:4}\",\n    \"0-0\": \"request_id\\n*(optional)*\",\n    \"0-1\": \"Your Request ID. Request ID will be returned as part of the trigger response.\",\n    \"0-2\": \"String\",\n    \"0-3\": \"1212c18475ff021108d127cd66\",\n    \"1-1\": \"If available, Google Advertising ID/Apple's IDFA generated by the device OS.\",\n    \"1-3\": \"a08172ff-89a6-43cc-825d-98afd7f6c22b\",\n    \"1-2\": \"String\",\n    \"1-0\": \"advertising_id\\n*(optional)*\",\n    \"5-0\": \"hosting_app\\n*(optional)*\",\n    \"5-1\": \"The host app package name.\",\n    \"5-2\": \"String\",\n    \"5-3\": \"com.whatsapp\",\n    \"4-0\": \"sdk_version\\n*(optional)*\",\n    \"4-1\": \"Your location Tracking SDK version.\",\n    \"4-2\": \"String\",\n    \"4-3\": \"1.5.9\",\n    \"3-0\": \"events\\n*(mandatory)*\",\n    \"3-1\": \"The details of the visit start time, end time and with the location, WiFi and iBeacon signals collected. You may set up to 10 different visits in each request.\",\n    \"3-2\": \"JSON Array of [Events Structure](#section-events-structure)\"\n  },\n  \"cols\": 4,\n  \"rows\": 13\n}\n[/block]\n##Events Structure\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Field\",\n    \"h-1\": \"Description\",\n    \"h-2\": \"Type\",\n    \"h-3\": \"Example\",\n    \"1-0\": \"type\\n*(mandatory)*\",\n    \"1-1\": \"Event type. Either 'visit' or 'transit'.\",\n    \"1-2\": \"String\",\n    \"1-3\": \"\\\"visit\\\"\",\n    \"2-0\": \"start_time\\n*(mandatory)*\",\n    \"2-1\": \"Event start time in local-time with time zone.\",\n    \"2-2\": \"ISO-8601\",\n    \"2-3\": \"2016-11-02T08:27:30.189+0200\",\n    \"3-0\": \"end_time\\n*(mandatory)*\",\n    \"3-3\": \"2016-11-02T09:30:30.100+0200\",\n    \"3-1\": \"Event end time in local-time with time zone.\",\n    \"3-2\": \"ISO-8601\",\n    \"0-0\": \"event_id\\n*(mandatory)*\",\n    \"0-1\": \"Your event ID. Venue detection results will include this field in the response.\",\n    \"0-2\": \"String\",\n    \"0-3\": \"\\\"1q234f6678\\\"\",\n    \"4-0\": \"data\\n*(mandatory)*\",\n    \"4-1\": \"The data attribute contains an array of [Signals Structure](#section-signals-structure). \\nEach element within the array, may contain several signals and formats (location/Wi-Fi scans) with different timestamps. **However, all signals should fall within the event time-range.**\",\n    \"4-2\": \"JSON Array of [Signals Structure](doc:signals-structure)\"\n  },\n  \"cols\": 4,\n  \"rows\": 5\n}\n[/block]\n##VD-Request - Structured Visits - Example\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"request_id\\\": \\\"1212c18475ff021108d127cd66\\\",\\n  \\\"advertising_id\\\": \\\"a08172ff-89a6-43cc-825d-98afd7f6c22b\\\",\\n  \\\"user_id\\\": \\\"56c18475ff021108d127cda8\\\",\\n  \\\"device_brand\\\": \\\"LGE\\\",\\n  \\\"device_model\\\": \\\"LG-D850\\\",\\n  \\\"os\\\": \\\"Android\\\",\\n  \\\"os_version\\\": \\\"5.0.1\\\",\\n  \\\"hosting_app\\\": \\\"com.myApp\\\",\\n  \\\"events\\\": [\\n    {\\n      \\\"event_id\\\": \\\"1q234f6678\\\",\\n      \\\"type\\\": \\\"visit\\\",\\n      \\\"start_time\\\": \\\"2016-11-02T08:27:30.189+0200\\\",\\n      \\\"end_time\\\": \\\"2016-11-02T09:00:10.100+0200\\\",\\n      \\\"data\\\": [\\n        {\\n          \\\"timestamp\\\": \\\"2016-01-31T07:17:44-06:00\\\",\\n          \\\"location\\\": {\\n            \\\"lat\\\": 38.6214988,\\n            \\\"long\\\": -90.3297644,\\n            \\\"accuracy\\\": 50,\\n            \\\"speed\\\": 0.87,\\n            \\\"altitude\\\": 100\\n          }\\n        },\\n        {\\n          \\\"timestamp\\\": \\\"2016-01-31T07:15:44-06:00\\\",\\n          \\\"active_wifi\\\": {\\n            \\\"ssid\\\": \\\"Sonic.net-840\\\",\\n            \\\"bssid\\\": \\\"b8:3e:59:3a:45:f7\\\",\\n            \\\"strength\\\": -90\\n          },\\n          \\\"wifi_scan\\\": [\\n            {\\n              \\\"ssid\\\": \\\"Sonic.net-840\\\",\\n              \\\"bssid\\\": \\\"b8:3e:59:3a:45:f7\\\",\\n              \\\"strength\\\": -90,\\n              \\\"age\\\": 0\\n            },\\n            {\\n              \\\"ssid\\\": \\\"Mall-Free-WiFi\\\",\\n              \\\"bssid\\\": \\\"a5:12:59:3a:4a:a2\\\",\\n              \\\"strength\\\": -67,\\n              \\\"age\\\": 3\\n            }\\n          ]\\n        }\\n      ]\\n    }\\n  ]\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"VD-Request - Unstructured Visits\"\n}\n[/block]\nUse this format if your request does not contains visit start-time/end-time.\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Field\",\n    \"h-1\": \"Description\",\n    \"h-2\": \"Type\",\n    \"h-3\": \"Example\",\n    \"6-0\": \"os\\n\\n*(optional)*\",\n    \"8-0\": \"device_model\\n\\n*(optional)*\",\n    \"7-0\": \"os_version\\n\\n*(optional)*\",\n    \"7-1\": \"OS version.\",\n    \"8-1\": \"The device model.\",\n    \"6-1\": \"The device operating system: Android or iOS.\",\n    \"6-2\": \"String\",\n    \"7-2\": \"String\",\n    \"8-2\": \"String\",\n    \"8-3\": \"LG-D802\",\n    \"7-3\": \"4.4.2\",\n    \"6-3\": \"Android\",\n    \"9-0\": \"device_brand\\n*(optional)*\",\n    \"9-1\": \"The device brand.\",\n    \"9-2\": \"String\",\n    \"9-3\": \"LGE\",\n    \"2-0\": \"user_id\\n*(optional)*\",\n    \"2-1\": \"Should be used if advertising ID is not available. If both User ID and Advertising ID are provided, Placer will ignore the User ID.\",\n    \"2-2\": \"String\",\n    \"2-3\": \"56c18475ff021108d127cda8\",\n    \"10-0\": \"gender\\n*(optional)*\",\n    \"11-0\": \"yob\\n*(optional)*\",\n    \"10-1\": \"Gender: “M” male, “F” female, “O” Other.\",\n    \"11-1\": \"Year of birth as a 4-digit integer\",\n    \"11-2\": \"int\",\n    \"11-3\": \"1984\",\n    \"10-2\": \"String\",\n    \"10-3\": \"M\",\n    \"12-0\": \"custom_data\\n*(optional)*\",\n    \"12-1\": \"Developers can define custom data and attributes for each device. This data will be returned in the [Device Details Structure](doc:device-details).\",\n    \"12-2\": \"JSON\",\n    \"12-3\": \"{“number_of_family_members”:4}\",\n    \"0-0\": \"request_id\\n*(optional)*\",\n    \"0-1\": \"Your Request ID. Request ID will be returned as part of the trigger response.\",\n    \"0-2\": \"String\",\n    \"0-3\": \"1212c18475ff021108d127cd66\",\n    \"1-1\": \"If available, Google Advertising ID/Apple's IDFA generated by the device OS.\",\n    \"1-3\": \"a08172ff-89a6-43cc-825d-98afd7f6c22b\",\n    \"1-2\": \"String\",\n    \"1-0\": \"advertising_id\\n*(optional)*\",\n    \"5-0\": \"hosting_app\\n*(optional)*\",\n    \"5-1\": \"The host app package name.\",\n    \"5-2\": \"String\",\n    \"5-3\": \"com.whatsapp\",\n    \"4-0\": \"sdk_version\\n*(optional)*\",\n    \"4-1\": \"Your location Tracking SDK version.\",\n    \"4-2\": \"String\",\n    \"4-3\": \"1.5.9\",\n    \"3-1\": \"The data attribute contains an array of [Signals Structure](#section-signals-structure). \\nEach element within the array, may contain several signals and formats (location/Wi-Fi scans) with different timestamps.\",\n    \"3-0\": \"data\",\n    \"3-2\": \"JSON Array of [Signals Structure](doc:signals-structure)\"\n  },\n  \"cols\": 4,\n  \"rows\": 13\n}\n[/block]\n##VD-Request - Unstructured Visits - Example\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n\\t\\\"request_id\\\":\\\"1212c18475ff021108d127cd66\\\",\\n  \\\"advertising_id\\\": \\\"a08172ff-89a6-43cc-825d-98afd7f6c22b\\\",\\n  \\\"user_id\\\": \\\"56c18475ff021108d127cda8\\\",\\n  \\\"device_brand\\\": \\\"LGE\\\",\\n  \\\"device_model\\\": \\\"LG-D850\\\",\\n  \\\"os\\\": \\\"Android\\\",\\n  \\\"os_version\\\": \\\"5.0.1\\\",\\n  \\\"hosting_app\\\":\\\"com.myApp\\\",\\n  \\\"data\\\": [\\n    {\\n      \\\"timestamp\\\": \\\"2016-01-31T07:17:44-06:00\\\",\\n      \\\"location\\\": {\\n        \\\"lat\\\": 38.6214988,\\n        \\\"long\\\": -90.3297644,\\n        \\\"accuracy\\\": 50,\\n        \\\"speed\\\": 0.87,\\n        \\\"altitude\\\": 433\\n      }\\n    },\\n    {\\n      \\\"timestamp\\\": \\\"2016-01-31T07:15:44-06:00\\\",\\n      \\\"active_wifi\\\":{\\n          \\\"ssid\\\": \\\"Sonic.net-840\\\",\\n          \\\"bssid\\\": \\\"b8:3e:59:3a:45:f7\\\",\\n          \\\"strength\\\": -90\\n        },\\n      \\\"wifi_scan\\\": [\\n        {\\n          \\\"ssid\\\": \\\"Sonic.net-840\\\",\\n          \\\"bssid\\\": \\\"b8:3e:59:3a:45:f7\\\",\\n          \\\"strength\\\": -90,\\n          \\\"age\\\": 0,\\n        },\\n        {\\n          \\\"ssid\\\": \\\"Mall-Free-WiFi\\\",\\n          \\\"bssid\\\": \\\"a5:12:59:3a:4a:a2\\\",\\n          \\\"strength\\\": -67,\\n          \\\"age\\\": 3\\n        }\\n      ]\\n    }\\n  ]\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"VD-Trigger Response Structure\"\n}\n[/block]\nVD-Responses include the following JSON format. \n[block:callout]\n{\n  \"type\": \"warning\",\n  \"title\": \"Server Side Triggers Request Signing\",\n  \"body\": \"If you are using Server-2-Server postback URL to receive results, note that each trigger callback call has two additional parameters - \\\"Timestamp\\\" and a \\\"Signature\\\". For example: https://your-callback-server.com/triggers?timestamp=1455119126&signature=0936e117debe91a0de827d8cf066bb90474f1d39\\n\\n**Signature** combined with **Timestamp** may be used to validate the origin and the authenticity of the trigger. To better understand how Placer generates signatures using your App Secret, please see [Authentication](doc:server-2-server-rest-api).\\n\\nTo get you started quickly with validating signatures, please see a python example [here](https://storage.googleapis.com/public_drops/trigger_signature_validator.py).\"\n}\n[/block]\n\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Field\",\n    \"h-1\": \"Description\",\n    \"0-0\": \"id\",\n    \"0-1\": \"The trigger ID. Example: 56eea860fdef26678540cdb7\",\n    \"h-2\": \"Example\",\n    \"0-2\": \"56eea860fdef26678540cdb7\",\n    \"3-0\": \"user_info\",\n    \"3-1\": \"Contains the User ID, Device ID, App Key and Custom Data.\",\n    \"4-0\": \"visit\",\n    \"4-1\": \"Contains the visit information and place information. See [Visit Structure](doc:visit)\",\n    \"1-0\": \"request_id\",\n    \"1-1\": \"Your request ID.\",\n    \"2-0\": \"event_id\",\n    \"2-1\": \"If provided, your event ID.\"\n  },\n  \"cols\": 2,\n  \"rows\": 5\n}\n[/block]\n##Example\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"data\\\": {\\n   \\t\\\"id\\\": \\\"56eea860fdef26678540cdb7\\\",\\n\\t\\t\\\"request_id\\\":\\\"1212c18475ff021108d127cd66\\\",\\n    \\\"event_id\\\":\\\"5812a1c9fdef26427a455153\\\",\\n    \\\"user_info\\\": {\\n      \\\"user_id\\\": \\\"YOUR_USER_ID\\\",\\n      \\\"device_id\\\": \\\"5772c1b9fdef26427a455153\\\"\\n    },\\n    \\\"visit\\\": {\\n      \\\"event_type\\\": \\\"visit\\\",\\n      \\\"is_confirmed\\\": false,\\n      \\\"start_time\\\": \\\"2016-10-04T10:47:12.000-07:00\\\",\\n      \\\"place_id\\\": \\\"57f3e746e4b01d4af1e1c050\\\",\\n      \\\"place\\\": {\\n        \\\"estimated_address\\\": {\\n          \\\"city\\\": \\\"San Francisco\\\",\\n          \\\"country\\\": \\\"United States\\\",\\n          \\\"state\\\": \\\"California\\\",\\n          \\\"formatted_city\\\": \\\"San Francisco, California, United States\\\",\\n          \\\"postal_code\\\": \\\"94103\\\",\\n          \\\"formatted_address\\\": \\\"135 4th Street, San Francisco, California, United States\\\",\\n          \\\"street_address\\\": \\\"135 4th Street\\\"\\n        },\\n        \\\"estimated_geolocation\\\": {\\n          \\\"lat\\\": 37.784469903416,\\n          \\\"long\\\": -122.40330482239,\\n          \\\"accuracy\\\": 3.3771327633926\\n        },\\n        \\\"type_id\\\": 20,\\n        \\\"venue_info\\\": {\\n          \\\"category\\\": \\\"Shop & Service\\\",\\n          \\\"name\\\": \\\"Metreon\\\",\\n          \\\"probability\\\": 0.85,\\n          \\\"sub_category\\\": \\\"Mall\\\"\\n        },\\n        \\\"first_visit_time\\\": \\\"2016-10-04T16:03:11.000Z\\\",\\n        \\\"venues\\\": [\\n          {\\n          \\t\\\"category\\\": \\\"Shop & Service\\\",\\n\\t          \\\"name\\\": \\\"Metreon\\\",\\n  \\t        \\\"probability\\\": 0.85,\\n    \\t      \\\"sub_category\\\": \\\"Mall\\\"\\n        \\t},\\n          {\\n            \\\"category\\\": \\\"Food\\\",\\n            \\\"name\\\": \\\"Mel's Drive-In\\\",\\n            \\\"probability\\\": 0.06,\\n            \\\"sub_category\\\": \\\"Diner\\\"\\n          },\\n          {\\n            \\\"category\\\": \\\"Shop & Service\\\",\\n            \\\"name\\\": \\\"Off the Grid: 5M :::at::: Fifth and Minna\\\",\\n            \\\"probability\\\": 0.04,\\n            \\\"sub_category\\\": \\\"Street Food Gathering\\\"\\n          },\\n          {\\n            \\\"category\\\": \\\"Food\\\",\\n            \\\"name\\\": \\\"Sharetea\\\",\\n            \\\"probability\\\": 0.04,\\n            \\\"sub_category\\\": \\\"Bubble Tea Shop\\\"\\n          }\\n        ],\\n        \\\"last_visit_time\\\": \\\"2016-10-04T17:54:21.000Z\\\",\\n        \\\"type\\\": \\\"Shop & Service\\\",\\n        \\\"id\\\": \\\"57f3e746e4b01d4af1e1c050\\\"\\n      },\\n      \\\"id\\\": \\\"57f3eccdfdef263fe1e66df8\\\"\\n    }\\n  },\\n  \\\"result\\\": \\\"SUCCESS\\\"\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"VD-Synchronous Response Structure\"\n}\n[/block]\nJSON array of the following:\n[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"event_id\",\n    \"1-0\": \"visit\",\n    \"0-1\": \"If provided, your event ID.\",\n    \"1-1\": \"Contains the visit information and place information. See [Visit Structure](doc:visit)\"\n  },\n  \"cols\": 3,\n  \"rows\": 2\n}\n[/block]\n##Example\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"data\\\": [\\n    {\\n      \\\"event_id\\\": \\\"5812a1c9fdef26427a455153\\\",\\n      \\\"visit\\\": {\\n        \\\"event_type\\\": \\\"visit\\\",\\n        \\\"is_confirmed\\\": false,\\n        \\\"start_time\\\": \\\"2016-10-04T10:47:12.000-07:00\\\",\\n        \\\"place_id\\\": \\\"57f3e746e4b01d4af1e1c050\\\",\\n        \\\"place\\\": {\\n          \\\"estimated_address\\\": {\\n            \\\"city\\\": \\\"San Francisco\\\",\\n            \\\"country\\\": \\\"United States\\\",\\n            \\\"state\\\": \\\"California\\\",\\n            \\\"formatted_city\\\": \\\"San Francisco, California, United States\\\",\\n            \\\"postal_code\\\": \\\"94103\\\",\\n            \\\"formatted_address\\\": \\\"135 4th Street, San Francisco, California, United States\\\",\\n            \\\"street_address\\\": \\\"135 4th Street\\\"\\n          },\\n          \\\"estimated_geolocation\\\": {\\n            \\\"lat\\\": 37.784469903416,\\n            \\\"long\\\": -122.40330482239,\\n            \\\"accuracy\\\": 3.3771327633926\\n          },\\n          \\\"type_id\\\": 20,\\n          \\\"venue_info\\\": {\\n            \\\"category\\\": \\\"Shop & Service\\\",\\n            \\\"name\\\": \\\"Metreon\\\",\\n            \\\"probability\\\": 0.85,\\n            \\\"sub_category\\\": \\\"Mall\\\"\\n          },\\n          \\\"first_visit_time\\\": \\\"2016-10-04T16:03:11.000Z\\\",\\n          \\\"venues\\\": [\\n            {\\n              \\\"category\\\": \\\"Shop & Service\\\",\\n              \\\"name\\\": \\\"Metreon\\\",\\n              \\\"probability\\\": 0.85,\\n              \\\"sub_category\\\": \\\"Mall\\\"\\n            },\\n            {\\n              \\\"category\\\": \\\"Food\\\",\\n              \\\"name\\\": \\\"Mel's Drive-In\\\",\\n              \\\"probability\\\": 0.06,\\n              \\\"sub_category\\\": \\\"Diner\\\"\\n            },\\n            {\\n              \\\"category\\\": \\\"Shop & Service\\\",\\n              \\\"name\\\": \\\"Off the Grid: 5M @ Fifth and Minna\\\",\\n              \\\"probability\\\": 0.04,\\n              \\\"sub_category\\\": \\\"Street Food Gathering\\\"\\n            },\\n            {\\n              \\\"category\\\": \\\"Food\\\",\\n              \\\"name\\\": \\\"Sharetea\\\",\\n              \\\"probability\\\": 0.04,\\n              \\\"sub_category\\\": \\\"Bubble Tea Shop\\\"\\n            }\\n          ],\\n          \\\"last_visit_time\\\": \\\"2016-10-04T17:54:21.000Z\\\",\\n          \\\"type\\\": \\\"Shop & Service\\\",\\n          \\\"id\\\": \\\"57f3e746e4b01d4af1e1c050\\\"\\n        },\\n        \\\"id\\\": \\\"57f3eccdfdef263fe1e66df8\\\"\\n      }\\n    }\\n  ],\\n  \\\"result\\\": \\\"SUCCESS\\\"\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]","excerpt":"","slug":"venue-detection","type":"basic","title":"Near-Real-Time Venue Detection API"}

Near-Real-Time Venue Detection API


Use Placer's Near-Real-Time Venue Detection API (VD-API) to identify venues currently being visited by your mobile users. The VD-API resolves location coordinates, Wi-Fi and beacon scans, collected by your mobile app/SDK to venue details, in near-real-time. [block:callout] { "type": "info", "title": "Before you start", "body": "Contact your Placer account manager for your 'VD-API URL', App-Key and App-Secret. \nAlso, let us know if you are interested in trigger (postback URL) response, a synchronous response or bucket export (see explanation below)." } [/block] [block:api-header] { "title": "How it works" } [/block] ##Request Send a VD-Request to Placer's VD-API URL of one of the following types: * [Structured Visits (visits with start/end time)](#vd-request-structured-visits) * [Unstructured Visits (visits without start/end time)](#vd-request-unstructured-visits) ##Response Results can be provided in either one of the following methods. Please contact your account manager to configure the desired solution: * **Server Side Trigger** - For each visit, Placer will generate a [VD-Trigger-Response](#vd-trigger-response-structure) with the venue name, category and additional details. Triggers will be sent to your server's postback URL within 1 minute. * **Bucket Export** - For each visit, Placer will generate a [VD-Trigger-Response](#vd-trigger-response-structure) that will be exported to your AWS/GCS bucket (see [Data Export](doc:data-export)). * **A synchronous response** - generates an immediate [VD-Synchronous Response](#vd-synchronous-response-structure) response with the results. [block:callout] { "type": "warning", "body": "- Placer uses a hash-based message authentication code (HMAC) for server to server queries. Each request should include a **timestamp** and **signature**, as described in the [Authentication](doc:server-2-server-rest-api) section. \n- Request content should be compressed using gzip with the following http header - **Content-Encoding: gzip**", "title": "Note" } [/block] [block:api-header] { "type": "basic", "title": "VD-Request - Structured Visits" } [/block] Use this format if your request includes visit start/end time or multiple events. [block:parameters] { "data": { "h-0": "Field", "h-1": "Description", "h-2": "Type", "h-3": "Example", "6-0": "os\n*(optional)*", "8-0": "device_model\n*(optional)*", "7-0": "os_version\n*(optional)*", "7-1": "OS version.", "8-1": "The device model.", "6-1": "The device operating system: Android or iOS.", "6-2": "String", "7-2": "String", "8-2": "String", "8-3": "LG-D802", "7-3": "4.4.2", "6-3": "Android", "9-0": "device_brand\n*(optional)*", "9-1": "The device brand.", "9-2": "String", "9-3": "LGE", "2-0": "user_id\n*(optional)*", "2-1": "Should be used if advertising ID is not available. If both User ID and Advertising ID are provided, Placer will ignore the User ID.", "2-2": "String", "2-3": "56c18475ff021108d127cda8", "10-0": "gender\n*(optional)*", "11-0": "yob\n*(optional)*", "10-1": "Gender: “M” male, “F” female, “O” Other.", "11-1": "Year of birth as a 4-digit integer", "11-2": "int", "11-3": "1984", "10-2": "String", "10-3": "M", "12-0": "custom_data\n*(optional)*", "12-1": "Developers can define custom data and attributes for each device. This data will be returned in the [Device Details Structure](doc:device-details).", "12-2": "JSON", "12-3": "{“number_of_family_members”:4}", "0-0": "request_id\n*(optional)*", "0-1": "Your Request ID. Request ID will be returned as part of the trigger response.", "0-2": "String", "0-3": "1212c18475ff021108d127cd66", "1-1": "If available, Google Advertising ID/Apple's IDFA generated by the device OS.", "1-3": "a08172ff-89a6-43cc-825d-98afd7f6c22b", "1-2": "String", "1-0": "advertising_id\n*(optional)*", "5-0": "hosting_app\n*(optional)*", "5-1": "The host app package name.", "5-2": "String", "5-3": "com.whatsapp", "4-0": "sdk_version\n*(optional)*", "4-1": "Your location Tracking SDK version.", "4-2": "String", "4-3": "1.5.9", "3-0": "events\n*(mandatory)*", "3-1": "The details of the visit start time, end time and with the location, WiFi and iBeacon signals collected. You may set up to 10 different visits in each request.", "3-2": "JSON Array of [Events Structure](#section-events-structure)" }, "cols": 4, "rows": 13 } [/block] ##Events Structure [block:parameters] { "data": { "h-0": "Field", "h-1": "Description", "h-2": "Type", "h-3": "Example", "1-0": "type\n*(mandatory)*", "1-1": "Event type. Either 'visit' or 'transit'.", "1-2": "String", "1-3": "\"visit\"", "2-0": "start_time\n*(mandatory)*", "2-1": "Event start time in local-time with time zone.", "2-2": "ISO-8601", "2-3": "2016-11-02T08:27:30.189+0200", "3-0": "end_time\n*(mandatory)*", "3-3": "2016-11-02T09:30:30.100+0200", "3-1": "Event end time in local-time with time zone.", "3-2": "ISO-8601", "0-0": "event_id\n*(mandatory)*", "0-1": "Your event ID. Venue detection results will include this field in the response.", "0-2": "String", "0-3": "\"1q234f6678\"", "4-0": "data\n*(mandatory)*", "4-1": "The data attribute contains an array of [Signals Structure](#section-signals-structure). \nEach element within the array, may contain several signals and formats (location/Wi-Fi scans) with different timestamps. **However, all signals should fall within the event time-range.**", "4-2": "JSON Array of [Signals Structure](doc:signals-structure)" }, "cols": 4, "rows": 5 } [/block] ##VD-Request - Structured Visits - Example [block:code] { "codes": [ { "code": "{\n \"request_id\": \"1212c18475ff021108d127cd66\",\n \"advertising_id\": \"a08172ff-89a6-43cc-825d-98afd7f6c22b\",\n \"user_id\": \"56c18475ff021108d127cda8\",\n \"device_brand\": \"LGE\",\n \"device_model\": \"LG-D850\",\n \"os\": \"Android\",\n \"os_version\": \"5.0.1\",\n \"hosting_app\": \"com.myApp\",\n \"events\": [\n {\n \"event_id\": \"1q234f6678\",\n \"type\": \"visit\",\n \"start_time\": \"2016-11-02T08:27:30.189+0200\",\n \"end_time\": \"2016-11-02T09:00:10.100+0200\",\n \"data\": [\n {\n \"timestamp\": \"2016-01-31T07:17:44-06:00\",\n \"location\": {\n \"lat\": 38.6214988,\n \"long\": -90.3297644,\n \"accuracy\": 50,\n \"speed\": 0.87,\n \"altitude\": 100\n }\n },\n {\n \"timestamp\": \"2016-01-31T07:15:44-06:00\",\n \"active_wifi\": {\n \"ssid\": \"Sonic.net-840\",\n \"bssid\": \"b8:3e:59:3a:45:f7\",\n \"strength\": -90\n },\n \"wifi_scan\": [\n {\n \"ssid\": \"Sonic.net-840\",\n \"bssid\": \"b8:3e:59:3a:45:f7\",\n \"strength\": -90,\n \"age\": 0\n },\n {\n \"ssid\": \"Mall-Free-WiFi\",\n \"bssid\": \"a5:12:59:3a:4a:a2\",\n \"strength\": -67,\n \"age\": 3\n }\n ]\n }\n ]\n }\n ]\n}", "language": "json" } ] } [/block] [block:api-header] { "title": "VD-Request - Unstructured Visits" } [/block] Use this format if your request does not contains visit start-time/end-time. [block:parameters] { "data": { "h-0": "Field", "h-1": "Description", "h-2": "Type", "h-3": "Example", "6-0": "os\n\n*(optional)*", "8-0": "device_model\n\n*(optional)*", "7-0": "os_version\n\n*(optional)*", "7-1": "OS version.", "8-1": "The device model.", "6-1": "The device operating system: Android or iOS.", "6-2": "String", "7-2": "String", "8-2": "String", "8-3": "LG-D802", "7-3": "4.4.2", "6-3": "Android", "9-0": "device_brand\n*(optional)*", "9-1": "The device brand.", "9-2": "String", "9-3": "LGE", "2-0": "user_id\n*(optional)*", "2-1": "Should be used if advertising ID is not available. If both User ID and Advertising ID are provided, Placer will ignore the User ID.", "2-2": "String", "2-3": "56c18475ff021108d127cda8", "10-0": "gender\n*(optional)*", "11-0": "yob\n*(optional)*", "10-1": "Gender: “M” male, “F” female, “O” Other.", "11-1": "Year of birth as a 4-digit integer", "11-2": "int", "11-3": "1984", "10-2": "String", "10-3": "M", "12-0": "custom_data\n*(optional)*", "12-1": "Developers can define custom data and attributes for each device. This data will be returned in the [Device Details Structure](doc:device-details).", "12-2": "JSON", "12-3": "{“number_of_family_members”:4}", "0-0": "request_id\n*(optional)*", "0-1": "Your Request ID. Request ID will be returned as part of the trigger response.", "0-2": "String", "0-3": "1212c18475ff021108d127cd66", "1-1": "If available, Google Advertising ID/Apple's IDFA generated by the device OS.", "1-3": "a08172ff-89a6-43cc-825d-98afd7f6c22b", "1-2": "String", "1-0": "advertising_id\n*(optional)*", "5-0": "hosting_app\n*(optional)*", "5-1": "The host app package name.", "5-2": "String", "5-3": "com.whatsapp", "4-0": "sdk_version\n*(optional)*", "4-1": "Your location Tracking SDK version.", "4-2": "String", "4-3": "1.5.9", "3-1": "The data attribute contains an array of [Signals Structure](#section-signals-structure). \nEach element within the array, may contain several signals and formats (location/Wi-Fi scans) with different timestamps.", "3-0": "data", "3-2": "JSON Array of [Signals Structure](doc:signals-structure)" }, "cols": 4, "rows": 13 } [/block] ##VD-Request - Unstructured Visits - Example [block:code] { "codes": [ { "code": "{\n\t\"request_id\":\"1212c18475ff021108d127cd66\",\n \"advertising_id\": \"a08172ff-89a6-43cc-825d-98afd7f6c22b\",\n \"user_id\": \"56c18475ff021108d127cda8\",\n \"device_brand\": \"LGE\",\n \"device_model\": \"LG-D850\",\n \"os\": \"Android\",\n \"os_version\": \"5.0.1\",\n \"hosting_app\":\"com.myApp\",\n \"data\": [\n {\n \"timestamp\": \"2016-01-31T07:17:44-06:00\",\n \"location\": {\n \"lat\": 38.6214988,\n \"long\": -90.3297644,\n \"accuracy\": 50,\n \"speed\": 0.87,\n \"altitude\": 433\n }\n },\n {\n \"timestamp\": \"2016-01-31T07:15:44-06:00\",\n \"active_wifi\":{\n \"ssid\": \"Sonic.net-840\",\n \"bssid\": \"b8:3e:59:3a:45:f7\",\n \"strength\": -90\n },\n \"wifi_scan\": [\n {\n \"ssid\": \"Sonic.net-840\",\n \"bssid\": \"b8:3e:59:3a:45:f7\",\n \"strength\": -90,\n \"age\": 0,\n },\n {\n \"ssid\": \"Mall-Free-WiFi\",\n \"bssid\": \"a5:12:59:3a:4a:a2\",\n \"strength\": -67,\n \"age\": 3\n }\n ]\n }\n ]\n}", "language": "json" } ] } [/block] [block:api-header] { "type": "basic", "title": "VD-Trigger Response Structure" } [/block] VD-Responses include the following JSON format. [block:callout] { "type": "warning", "title": "Server Side Triggers Request Signing", "body": "If you are using Server-2-Server postback URL to receive results, note that each trigger callback call has two additional parameters - \"Timestamp\" and a \"Signature\". For example: https://your-callback-server.com/triggers?timestamp=1455119126&signature=0936e117debe91a0de827d8cf066bb90474f1d39\n\n**Signature** combined with **Timestamp** may be used to validate the origin and the authenticity of the trigger. To better understand how Placer generates signatures using your App Secret, please see [Authentication](doc:server-2-server-rest-api).\n\nTo get you started quickly with validating signatures, please see a python example [here](https://storage.googleapis.com/public_drops/trigger_signature_validator.py)." } [/block] [block:parameters] { "data": { "h-0": "Field", "h-1": "Description", "0-0": "id", "0-1": "The trigger ID. Example: 56eea860fdef26678540cdb7", "h-2": "Example", "0-2": "56eea860fdef26678540cdb7", "3-0": "user_info", "3-1": "Contains the User ID, Device ID, App Key and Custom Data.", "4-0": "visit", "4-1": "Contains the visit information and place information. See [Visit Structure](doc:visit)", "1-0": "request_id", "1-1": "Your request ID.", "2-0": "event_id", "2-1": "If provided, your event ID." }, "cols": 2, "rows": 5 } [/block] ##Example [block:code] { "codes": [ { "code": "{\n \"data\": {\n \t\"id\": \"56eea860fdef26678540cdb7\",\n\t\t\"request_id\":\"1212c18475ff021108d127cd66\",\n \"event_id\":\"5812a1c9fdef26427a455153\",\n \"user_info\": {\n \"user_id\": \"YOUR_USER_ID\",\n \"device_id\": \"5772c1b9fdef26427a455153\"\n },\n \"visit\": {\n \"event_type\": \"visit\",\n \"is_confirmed\": false,\n \"start_time\": \"2016-10-04T10:47:12.000-07:00\",\n \"place_id\": \"57f3e746e4b01d4af1e1c050\",\n \"place\": {\n \"estimated_address\": {\n \"city\": \"San Francisco\",\n \"country\": \"United States\",\n \"state\": \"California\",\n \"formatted_city\": \"San Francisco, California, United States\",\n \"postal_code\": \"94103\",\n \"formatted_address\": \"135 4th Street, San Francisco, California, United States\",\n \"street_address\": \"135 4th Street\"\n },\n \"estimated_geolocation\": {\n \"lat\": 37.784469903416,\n \"long\": -122.40330482239,\n \"accuracy\": 3.3771327633926\n },\n \"type_id\": 20,\n \"venue_info\": {\n \"category\": \"Shop & Service\",\n \"name\": \"Metreon\",\n \"probability\": 0.85,\n \"sub_category\": \"Mall\"\n },\n \"first_visit_time\": \"2016-10-04T16:03:11.000Z\",\n \"venues\": [\n {\n \t\"category\": \"Shop & Service\",\n\t \"name\": \"Metreon\",\n \t \"probability\": 0.85,\n \t \"sub_category\": \"Mall\"\n \t},\n {\n \"category\": \"Food\",\n \"name\": \"Mel's Drive-In\",\n \"probability\": 0.06,\n \"sub_category\": \"Diner\"\n },\n {\n \"category\": \"Shop & Service\",\n \"name\": \"Off the Grid: 5M @ Fifth and Minna\",\n \"probability\": 0.04,\n \"sub_category\": \"Street Food Gathering\"\n },\n {\n \"category\": \"Food\",\n \"name\": \"Sharetea\",\n \"probability\": 0.04,\n \"sub_category\": \"Bubble Tea Shop\"\n }\n ],\n \"last_visit_time\": \"2016-10-04T17:54:21.000Z\",\n \"type\": \"Shop & Service\",\n \"id\": \"57f3e746e4b01d4af1e1c050\"\n },\n \"id\": \"57f3eccdfdef263fe1e66df8\"\n }\n },\n \"result\": \"SUCCESS\"\n}", "language": "json" } ] } [/block] [block:api-header] { "title": "VD-Synchronous Response Structure" } [/block] JSON array of the following: [block:parameters] { "data": { "0-0": "event_id", "1-0": "visit", "0-1": "If provided, your event ID.", "1-1": "Contains the visit information and place information. See [Visit Structure](doc:visit)" }, "cols": 3, "rows": 2 } [/block] ##Example [block:code] { "codes": [ { "code": "{\n \"data\": [\n {\n \"event_id\": \"5812a1c9fdef26427a455153\",\n \"visit\": {\n \"event_type\": \"visit\",\n \"is_confirmed\": false,\n \"start_time\": \"2016-10-04T10:47:12.000-07:00\",\n \"place_id\": \"57f3e746e4b01d4af1e1c050\",\n \"place\": {\n \"estimated_address\": {\n \"city\": \"San Francisco\",\n \"country\": \"United States\",\n \"state\": \"California\",\n \"formatted_city\": \"San Francisco, California, United States\",\n \"postal_code\": \"94103\",\n \"formatted_address\": \"135 4th Street, San Francisco, California, United States\",\n \"street_address\": \"135 4th Street\"\n },\n \"estimated_geolocation\": {\n \"lat\": 37.784469903416,\n \"long\": -122.40330482239,\n \"accuracy\": 3.3771327633926\n },\n \"type_id\": 20,\n \"venue_info\": {\n \"category\": \"Shop & Service\",\n \"name\": \"Metreon\",\n \"probability\": 0.85,\n \"sub_category\": \"Mall\"\n },\n \"first_visit_time\": \"2016-10-04T16:03:11.000Z\",\n \"venues\": [\n {\n \"category\": \"Shop & Service\",\n \"name\": \"Metreon\",\n \"probability\": 0.85,\n \"sub_category\": \"Mall\"\n },\n {\n \"category\": \"Food\",\n \"name\": \"Mel's Drive-In\",\n \"probability\": 0.06,\n \"sub_category\": \"Diner\"\n },\n {\n \"category\": \"Shop & Service\",\n \"name\": \"Off the Grid: 5M @ Fifth and Minna\",\n \"probability\": 0.04,\n \"sub_category\": \"Street Food Gathering\"\n },\n {\n \"category\": \"Food\",\n \"name\": \"Sharetea\",\n \"probability\": 0.04,\n \"sub_category\": \"Bubble Tea Shop\"\n }\n ],\n \"last_visit_time\": \"2016-10-04T17:54:21.000Z\",\n \"type\": \"Shop & Service\",\n \"id\": \"57f3e746e4b01d4af1e1c050\"\n },\n \"id\": \"57f3eccdfdef263fe1e66df8\"\n }\n }\n ],\n \"result\": \"SUCCESS\"\n}", "language": "json" } ] } [/block]