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:
- Our daily usage statistics API
- 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:
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:
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