Skip to main content

Tagging and Usage Tracking

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 requests with your key.

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

Tag a Request

For each property you can append a tag to your request using tags=. For instance, for webpage.co.uk you could append tags=a.

If you're using the HTTP API directly the request will go from:

/v1/autocomplete/addresses/paf_12345/gbr?api_key=iddqd

To this:

/v1/autocomplete/addresses/paf_12345/gbr?api_key=iddqd&tags=a

Multiple Tags Example

Tagging is available across all methods which affect your lookup balance. To use multiple tags, 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

Track by Tag

There are 2 ways to generate usage statistics:

  1. Our daily usage statistics API
  2. Our key usage CSV export API

Both are available on the dashboard. Click Filter by Tags and enter the tag (in this case a) to get back the usage:

usage dashboard

The tag will appear in your CSV usage log in the second-to-last column. The final column records the number of lookups consumed by the transaction:

usage excel

If you wish to do quite heavy analysis, we recommend outputting all your CSV usage without tag filtering. Then load the CSV into Excel and use Excel's Filter functionality to filter the tag column and do the analysis there.

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