From a8e5bebb9d4d2f402354a15ccba439edbb19e83b Mon Sep 17 00:00:00 2001
From: Simon Szustkowski <mail@simonszu.de>
Date: Thu, 24 Nov 2016 15:08:38 +0100
Subject: [PATCH] Proper documentation for foursquare (#1492)

---
 source/_components/foursquare.markdown | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/source/_components/foursquare.markdown b/source/_components/foursquare.markdown
index 582eae421df..c8070eff9a2 100644
--- a/source/_components/foursquare.markdown
+++ b/source/_components/foursquare.markdown
@@ -28,6 +28,20 @@ Configuration variables:
 - **access_token** (*Required*): A Foursquare API access token.
 - **push_secret** (*Required*): The push secret that Foursquare provides to you in the app dashboard.
 
+#### Getting the access token ####
+
+After you have registered your APP on your [My Apps Page](https://foursquare.com/developers/apps) you get a `CLIENT_ID` and you have specified a
+`REDIRECT_URL` which can be any URL you like, but since it will get your access token via a HTTP GET request, it should be a URL which will ignore the `access_token` HTTP GET variable. A good idea is to choose the URL of your Home Assistant. 
+Visit the following URL in your browser:
+
+```
+https://foursquare.com/oauth2/authenticate?client_id=CLIENT_ID&response_type=token&redirect_uri=YOUR_REGISTERED_REDIRECT_URI
+```
+
+and change the `CLIENT_ID` and `YOUR_REGISTERED_REDIRECT_URL` to your actual values. 
+You will receive an OAuth request landing page, asking you if you want to connect your Foursquare account to your newly created app. Say "Yes".
+After that, you will get redirected to your `REDIRECT_URL` with the `access_token` as a HTTP GET variable. Copy everything after the = and paste it in your configuration.yaml as the `access_token`.
+
 ### {% linkable_title Real-Time API %}
 
 The component accepts pushes from Foursquare at `/api/foursquare`. The route does not require authentication.