What is it?

This device type allows the plug-in to process position data received via an http POST or GET request. See below for the correct URL formatting and accepted parameters.

This type of device can be used when the user has control over the formatting of the request data.

A group of HS3 devices will be created that includes all possible data types.

Add a new Custom Position User/Device Type

From the User / Devices configuration page, select Custom Position (P)

General Options

Device Enabled

Enable / Disable this device.

Device Id

By default the plug-in will assign the HS3 device ref as the DeviceId. This can be changed but should be a unique value amongst position type devices.

Minimum distance to move

This is the minimum distance that a new position update must be from the last known position for it to be considered as new.

Recommended starting value for this field is 0.5 miles or 0.8 kilometres

Ignore new position if accuracy > (metres)

If the reported accuracy of the new position > this value then the position will be ignored. Accuracy is always shown in metres regardless of the units setting.

Recommended starting value for this field is 2000 metres.

Show Address Only

If enabled hyper-links and additional data will not be added to the Street Address device for this user.

Record to Database

If selected, both new position updates will be recorded to the plug-in's database for later viewing / mapping.

Dynamic Mapping Options

Build a New Map when Location Changes

If enabled a new dynamic map of the device's current location will be created whenever its location is updated.

By default the map file will be saved as \HS3\html\PHLocation2\Maps\XXXX_current.html where XXXX is the DeviceId.

Map Icon (Google Only)

This option allows specifying different map marker icons on Google maps only. All other map providers have fixed icons.

Map Marker Character

Choose the character displayed on the dynamic map marker. Valid choices are A to Z or Off.

Initial Map Type

Specifies the map type that is initially set when a map is displayed on the internal map viewer.

Initial Max Zoom Level

On a single point or multi-point map where all points are very close together, the map can sometimes be over-zoomed making it difficult to read.

This options allows setting a max initial zoom level so the map won't open in an over-zoomed state.

Under normal circumstances leave this set at Auto and the plug-in will handle the correct zoom level.

Map Size

Set the size of the map. Max size is 1000 x 1000 px.

Override File Path / Name

By default the auto-generated all users map will be saved to:

\HS3\html\PHLocation2\Maps and the file name will be all_users_current.html

The path and/or file name can be overridden using these settings.

The file name can take replacement variables which must be enclosed between the dollar symbol like $variable$.
You can specify multiple variables together ($YMD$) or singularly ($Y$/$D$/$M$).
Supported variables are
A=Yesterday's date (YYYYMMDD)
Y=Current Year (YYYY)
M=Current Month (MM)
D=Current Day (DD)
h=Current Hour (hh)
m=Current Minute (mm)
s=Current Second (ss)

Include this device on All Users Dynamic Map

If enabled, this device's current location will be included on the all users dynamic map. See here for options relating to the all users map.

Rebuild Child Devices Button

If a child device has been deleted or new features are added in a future plug-in release that require additional child devices, then this function will rebuild any missing child devices and add them to the group.

Base URL

For direct connection to HS3's web server: http://yourhomeseerserver/phl2api?dtype=CD&type=P

NOTE: https is supported if your HS3 web server is configured for https access.

For connection via MyHS: https://connected2.homeseer.com/phl2api?dtype=CD&type=P


Both connection methods require the request to be authenticated. If using the MyHS method then use your MyHS credentials. For a direct connection use a valid HS3 user/pass combination.

A typical complete URL to send a basic position report might look like:


The minimum data required for a location to be processed is phlid, Latitude, Longitude and Accuracy

Additional parameters can be added to the end of the URL as required.

Supported parameters are:

Parameter Name


Accepted Values


Latitude in decimal degrees

From -90 To 90


Longitude in decimal degrees

From -180 To 180


Fix accuracy in metres



Time of fix

Unix Time


The device ID as configured in HS3 for the user

Integer >0


Speed in whatever units the plug-in is configured for



Fix Course in degrees

From 0 To 360


Fix Provider

0=Unknown 1=GPS 2=Network 3=WiFi


Device Charging State

0=Not Charging 1=Charging


Device Online State

0=Off-Line 1=On-Line


Altitude in Metres or Feet

Any numerical value


Battery Level in %

From 0 To 100

Created with the Personal Edition of HelpNDoc: Benefits of a Help Authoring Tool