API Specifications
To be unobtrusive to your end-users, we’ll respond with a 200
OK status, even if some of these parameters are “incorrect”. The
response will be a 1x1 GIF image (to power our ”
Beacon API”).
Recording an Event
Method URL:
http://trk.kissmetrics.com/e
https://trk.kissmetrics.com/e
Parameters (GET)
Parameters | Format | Necessary? | Description |
_k | string | Yes | Your API key |
_p | 255 char string | Yes | Person doing the event |
_n | URL-encoded string | Yes | Name of the event |
_t | integer | optional | Timestamp in seconds after UTC Unix epoch |
_d | 0 or 1 | optional | Set to 1 if you’re manually passing us the timestamp. It’s used when logging events that occurred in the past. |
(Anything) | URL-encoded string | optional | Set an arbitrary value to an arbitrary user property |
Example
http://trk.kissmetrics.com/e?_k=api-key&_p=bob&_n=Signed+Up&gender=male&_t=1262304000&_d=1
This records that the user
bob
did the event
Signed Up
and his
gender
was
male
and this all happened on midnight of January 1, 2010 UTC.
Please be aware of how our processing servers detect
duplicate events.
Setting Properties
Method URL:
http://trk.kissmetrics.com/s
https://trk.kissmetrics.com/s
Parameters (GET)
Parameters | Format | Necessary? | Description |
_k | string | Yes | Your API key |
_p | 255 char string | Yes | Person doing the event |
(Anything) | URL-encoded string | optional | Set an arbitrary value to an arbitrary user property |
_t | integer | optional | Timestamp in seconds after UTC Unix epoch |
_d | 0 or 1 | optional | Set to 1 if you’re manually passing us the timestamp. It’s used when logging events that occurred in the past. |
Example
http://trk.kissmetrics.com/s?_k=api-key&_p=bob&gender=male&_t=1262304000&_d=1
This records that the user
bob
got the property
gender
with the value set to
male
and this happened on midnight of January 1, 2010 UTC.
Please be aware of how our processing servers detect
duplicate properties.
Aliasing Users
Method URL:
http://trk.kissmetrics.com/a
https://trk.kissmetrics.com/a
Parameters (GET)
Parameters | Format | Necessary? | Description |
_k | string | Yes | Your API key |
_p | 255 char string | Yes | One of the person’s identities |
_n | 255 char string | Yes | Another of the person’s identities |
Example
http://trk.kissmetrics.com/a?_k=api-key&_p=bob&_n=bob%40bob.com
This tells us to treat
bob
and
bob@bob.com
as the same person. If you log events or properties to either ID, they all refer back to the same one person. (
bob@bob.com
is passed as
bob%40bob.com
because the
@
needs to be
URL-encoded.)
You most frequently use this to connect a person’s ID when
they are anonymous with the same person’s ID when they are known (that
is, to connect a randomly generated ID with their username, an email
address, Facebook ID, whatever).
It’s OK to call this more than once with the same pair of identities. It’s also OK if a person has more than one alias.