locations.php¶

Location management module for handling location data, tags, and history retrieval.

API Methods¶

Method	Action	Description
`add_tag`	get add tag	Adds a new tag to a specific location.
`clone`	get clone	Clones an existing location configuration.
`delete_tag`	get delete tag	Deletes an existing tag.
`get`	get location by id or code	Retrieves a specific location's data using its ID or alpha2 country code.
`history`	get history	Retrieves the history of changes for locations.
`list`	get list of locations	Returns a list of available locations, potentially excluding certain regions for customers.
`list_tags`	get list tags	Retrieves a list of all available tags.
`show`	get location by ID	Returns detailed information about a specific location, including its tags.
`update_tag`	update tag information	Updates the properties of an existing location tag.

locations/add_tag¶

Adds a new tag to a specific location.

HTTP method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `add_tag`
token	✅	string	Authentication token.
web_ip	❌	string	Client IP address used for authentication validation.
tag	✅	string	Tag name to be added.
value	❌	string	Value associated with the tag.
extra	❌	string	Additional metadata for the tag.
location_id	✅	integer	ID of the location where the tag will be added.
internal	❌	boolean	Flag indicating if the tag is internal.

Request example

curl -s "https://invapi.hostkey.com/locations.php" -X POST \
--data "action=add_tag" \
--data "token=HOSTKEY_TOKEN" \
--data "tag=VALUE" \
--data "location_id=123"

Success response example

{
"id": 123
}

Error examples

{
"code": -1,
"message": "invalid argument tag ''"
}

locations/clone¶

Clones an existing location configuration.

HTTP method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: clone
token	✅	string	Authentication token.
web_ip	❌	string	Client IP address used for authentication validation.
id	✅	integer	ID of the location to be cloned.

Request example

curl -s "https://invapi.hostkey.com/locations.php" -X POST \
--data "action=clone" \
--data "token=HOSTKEY_TOKEN" \
--data "id=VALUE"

Success response example

{
"Code": "US-NY",
"Name": "New York Data Center",
"description": "Cloned location configuration",
"status": "active"
}

Error examples

{
"code": -1,
"message": "invalid argument id '...'"
}

locations/delete_tag¶

Deletes an existing tag.

HTTP method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `delete_tag`
token	✅	string	Authentication token.
web_ip	❌	string	Client IP address used for authentication validation.
id	✅	integer	The unique identifier of the tag to be deleted.
location_id	✅	string	The ID or code of the location associated with the tag.

Request example

curl -s "https://invapi.hostkey.com/locations.php" -X POST \
--data "action=delete_tag" \
--data "token=HOSTKEY_TOKEN" \
--data "id=VALUE" \
--data "location_id=VALUE"

Success response example

{
"result": "OK",
"action": "delete_tag",
"data": {
"id": 123
}
}

Error examples

{
"code": -1,
"message": "invalid argument id '...'"
}

locations/get¶

Retrieves a specific location's data using its ID or alpha2 country code.

HTTP method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: get
token	✅	string	Authentication token.
web_ip	❌	string	Client IP address used for authentication validation.
id	❌	integer	Location ID or alpha2 country code.
location	❌	string	Alpha2 country code (e.g., US, NL).

Request example

curl -s "https://invapi.hostkey.com/locations.php" -X POST \
--data "action=get" \
--data "token=HOSTKEY_TOKEN"

Success response example

{
"result": "OK",
"action": "get",
"location": {
"ID": 10,
"Name": "Amsterdam",
"Code": "NL",
"Reg_zoneID": 5,
"status": "active"
}
}

Error examples

{
"code": -1,
"message": "Location loc:X does not exist"
}

locations/history¶

Retrieves the history of changes for locations.

HTTP method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `history`
token	✅	string	Authentication token.
web_ip	❌	string	Client IP address used for authentication validation.
id	✅	integer	Location ID to retrieve history for.

Request example

curl -s "https://invapi.hostkey.com/locations.php" -X POST \
--data "action=history" \
--data "token=HOSTKEY_TOKEN" \
--data "id=VALUE"

Success response example

{
"result": "OK",
"action": "history",
"data": [
{
"id": 1,
"date": "2023-01-01 10:00:00",
"description": "Location updated by admin { key = value }",
"type": "some_type",
"login": "admin"
}
]
}

Error examples

{
"code": -1,
"message": "invalid argument id '0'"
}

locations/list¶

Returns a list of available locations, potentially excluding certain regions for customers.

HTTP method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `list`
token	✅	string	Authentication token.
web_ip	❌	string	Client IP address used for authentication validation.

Request example

curl -s "https://invapi.hostkey.com/locations.php" -X POST \
--data "action=list" \
--data "token=HOSTKEY_TOKEN"

Success response example

{
"result": "OK",
"action": "list",
"locations": [
{
"id": 1,
"name": "Amsterdam",
"code": "NL"
},
{
"id": 2,
"name": "Frankfurt",
"code": "DE"
}
]
}

Error examples

{
"code": -1,
"message": "Action is not recognized"
}

locations/list_tags¶

Retrieves a list of all available tags.

HTTP method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `list_tags`
token	✅	string	Authentication token.
web_ip	❌	string	Client IP address used for authentication validation.
location_id	✅	integer	The ID of the location to retrieve tags for.

Request example

curl -s "https://invapi.hostkey.com/locations.php" -X POST \
--data "action=list_tags" \
--data "token=HOSTKEY_TOKEN" \
--data "location_id=VALUE"

Success response example

{
"tag": {
"tag": "string",
"id": "integer",
"location_id": "integer"
}
}

Error examples

{
"code": -1,
"message": "invalid argument location_id '{$params['location_id']}'"
}

locations/show¶

Returns detailed information about a specific location, including its tags.

HTTP method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: show
token	✅	string	Authentication token.
web_ip	❌	string	Client IP address used for authentication validation.
params[id]	✅	integer	The unique identifier of the location.

Request example

curl -s "https://invapi.hostkey.com/locations.php" -X POST \
--data "action=show" \
--data "token=HOSTKEY_TOKEN" \
--data "params[id]=1"

Success response example

{
"result": "OK",
"action": "show",
"data": {
"id": 1,
"name": "Amsterdam",
"code": "NL",
"tags": [
{
"id": 5,
"name": "High Speed"
}
]
}
}

Error examples

{
"code": -1,
"message": "Action is not recognized"
}

locations/update_tag¶

Updates the properties of an existing location tag.

HTTP method: POST

Parameters:

Parameter	Required	Type	Description
action	✅	string	Method identifier: `update_tag`
token	✅	string	Authentication token.
web_ip	❌	string	Client IP address used for authentication validation.
params[id]	✅	integer	The ID of the tag to update.
params[tag]	✅	string	The name or text of the tag.
params[location_id]	✅	string	The ID of the location associated with the tag.
params[value]	❌	string	Additional value for the tag.
params[extra]	❌	string	Extra information for the tag.
params[internal]	❌	integer	Internal flag for the tag. 1 if internal, 0 otherwise.

Request example

curl -s "https://invapi.hostkey.com/locations.php" -X POST \
--data "action=update_tag" \
--data "token=HOSTKEY_TOKEN" \
--data "params[id]=10" \
--data "params[tag]=MyTag" \
--data "params[location_id]=loc_123"

Success response example

{
"id": 10
}

Error examples

{
"code": -1,
"message": "invalid argument id '...'"
}