JSON API

HomeSeer can be controlled using JSON formatted data. Some notes on this API:

This API documented here is for use with HS4
Parameters are not case sensitive * most parameters accept "all" as an option to include all items, or if the parameter is not included "all" is assumed

To access the JSON API through the MyHS service, use the URL: https://connected2.homeseer.com/json. Previously we documented you to use myhs.homeseer.com/json but due to some technical issues we are are requiring you to go to connected2.homeseer.com. This URL is a "traffic manager" and not a direct server. It will route your request to the server has the lowest latency for your location.

Note that "connected2" is a traffic manager and will direct traffic to the best server by redirecting incoming traffic to the server that the correct HS server is connected to. To increase performance you can make a call that will tell you which system the HomeSeer server is connected to. Issue the following passing in the user/pass or token for the system you need to connect to:

https://myhs.homeseer.com/getsystems?user=USER&pass=PASS

or

https://myhs.homeseer.com/getsystems?token=TOKEN

This will return JSON that describes the available systems that are online as well as the server the system is connected to. You can grab the "tunnelip" URL and connect to that system directly. That will avoid a redirect at connected2.homeseer.com.

Note that this might return more than one system is if the user/pass points to a primary MyHS license. In that case you should display a dialog and allow the user to choose the system they wish to connect to. If the MyHS user does not have a MyHS premium subscription or the user/pass is a secondary user under a MyHS premium subscription, the JSON will point to a single system. If a token is passed, the response will always be a single system.

Sample JSON response:

JSON

 {
	"response": "ok",
	"responsecode": 200,
	"systems": [
		{
			"license": "123456",
			"friendly_name": "Home System",
			"hslocalip": "192.168.2.2:80",
			"hswanip": "0.0.0.0",
			"detected_wan_ip": "0.0.0.0",
			"tunnelip": "connected22.homeseer.com",
			"online": true
		}
	],
	"HasSubscription": false
}

HasSubscription: If True, the user is using a MyHS premium subscription

license: The license ID of the system

hslocalip: The local IP of the HS system, you can use this if you detect that the system is on the same network as the connecting client

hswanip: This is the WAN IP of the HS system.

detect_wan_ip: This is the detected WAN ip of the system making this request. If this IP and the hswanip are the same, then the connecting client is on the same network as the HS server and you can use the "hslocalip" to connect to the HS system. This will speed up response.

tunnelip: This is the IP of the server that is handling data for the HS system you are trying to connect to. Use this URL with all your JSON commands to access the target HS system. This will avoid redirects when connecting to "connected2.homeseer.com".

Testing:

Here is a sample URL that you can use for testing. Replace USER and PASS with the MyHS credentials for an online system:

https://connected2.homeseer.com/JSON?user=USER&pass=PASS&request=getstatus

The above URL can be used to access a system through our free MyHS service, just include the user/pass in the query string as shown, or in the HTTP header.

For accessing a local system, the user/pass is not required, just use the IP address of the system like:

http://IP_OF_SYSTEM/JSON?user=demo@homeseer.com&pass=demo100&request=getstatus

Notes

Make sure the query parameters are URL encoded otherwise the calls may fail. Use HttpUtility.URLEncode with .Net.
To obtain a token for a user's system using OAuth we must add your client ID and secret to our server. To provide us with a client ID and secret or request that we provide one please email Support@homeseer.com.