Tagging

Any request which affects your Key balance may be decorated with metadata called tags. This data is stored along with your lookup history and can be queried via the API. We call the ability to label your requests "tagging".

Tagging can be useful for recording the circumstances under which a request was made. For instance, you may use it to identify which of your servers, users or staff are performing request with your key.

Tagged requests can be queried or downloaded at a later date via our API or the dashboard.

Tagging Example

Tagging is available across all methods which affect your lookup balance. To use it, include a comma separated list of tags in the query string of your URI.

/v1/autocomplete/addresses/usps_99382|2|32|9923/gbr?api_key=key&tags=app1,usa

Notes

Tagging is only available via methods that drain your balance such as postcode or address search. Unsuccessful requests (i.e. non-2000 responses) do not affect your balance and so cannot be tagged.

You may query tagged requests via the /keys endpoint. The Key usage API allows you to query for usage by tag. The CSV lookup history API will also provide tag data with every request.

Tag storage and searching is also case sensitive.

Restrictions

There are a small number of restrictions on what may be tagged.

• You may only specify up to 5 tags per API request
• Each tag must not be longer than 16 UTF-8 characters