Return Mode

The return-mode parameter

return-mode can be one of two values, either 'url' or 'plain' (excluding the quotes)

URL

The return value from the gateway will be in the format of a http query string, for example:

status=200&desc=OK&longitude=10.2&latitude=-0.02&accuracy=0&timestamp=2020-09-11T16%3A07%3A58.000Z

Many languages provide an easy mechanism to decode the contents of such a string. For example:

• Java provides the class ServletRequest and function getParameterValues()
• Python provides the module urlparse and function parse_qs()
• PHP provides the function 'parse_str'

Plain

Using 'plain' instructs the gateway that you would like the response to be in the default format. If you also set the return-format parameter, the gateway will return the data back to you in the format you provide in the return-0format parameter (see below).

The return-format parameter

This parameter is only used if the return-mode parameter is set to 'plain'. This parameter allows you to set the format of the string returned back to you in the event of a success only. You simply need to embed the appropriate variables.

Example

Assume the gateway provides the variables status, description, longitude and latitude

If you would like all the variables returned to you on a single line seperated by a colon, you would use the following string:

status=%status%:description=%desc%:longitude=%longitude%:latitude=%latitude%

The gateway will replace %<variable_name>% with the contents of variable_name.

This would result in a response similar to:

status=200:description=Success:longitude=10:latitude=15

Note: Because you will be sending the request to us via HTTP, the whole of the return-format parameter would need to be url encoded. For this example, the urlencoded version is:

status%3D%25status%25%3Adescription%3D%25desc%25%3Alongitude%3D%25longitude%25%3Alatitude%3D%25latitude%25