@mattab opened this Issue on February 4th 2014 Owner

Our tracking API is fully documented at: Tracking API - tracking users analytics

It is also fully featured, and yet still a bit unstructured. Because we have added parameters one after the other when they were needed for useful features, now we realize that they could be named better, and be more structured.

Now that JSON has gone mainstream, it is natural to provide a pure JSON proxy to our good old named parameters. In the making, we could introduce structure in elements like events or ecommerce interactions (define each as a JSON object).

New API names proposals (to be discussed)

  • rec -> record
  • idsite -> idSite
  • url -> actionUrl
  • action_name -> actionName
  • gt_ms -> actionGenerationTimeMs
  • _id -> visitId
  • _cvar -> pageCustomVariables
  • urlref -> urlReferrer
  • _idvc -> visitCount
  • _viewts -> tsPreviousVisit
  • _idts -> tsFirstVisit
  • _rcn -> campaignName
  • _rck -> campaignKeyword
  • res -> resolution
  • h+m+s -> merge into userLocalTime
  • ua -> userAgent
  • lang -> userLanguage?
  • cvar -> pageCustomVariables
  • search -> searchKeyword
  • search_cat -> searchCategory
  • search_count -> searchResultsCount
  • idgoal -> idGoal
  • group all ec_* into "ecommerce" object
  • group all location info (country, region, city, latitude/longitude) into "location" object
  • group all events e_* into an "event" object
@mattab commented on September 9th 2014 Owner

See also #6000 Build a RESTful API for Piwik

@Spone commented on October 14th 2014

Hi @mattab ,

I've landed there from piwik/developer-documentation#28

I think you should consider using POST request for the Tracking API. Maybe you can also allow GET requests in case the client cannot do POST requests (Google Analytics does that), but the better HTTP verb to use in this case in POST (see here).

Some other thoughts:

apiv will now be passed in the URL (for instance http://mypiwik.com/api/v2/) if I understand correctly.

lang -> userLanguage?

I would name it locale or userLocale, and allow just ISO 639 (language) code (optionally with an ISO 3166-1 alpha-2 (2-letter country) code).

Also, I don't know if you're familiar with JSON Schema, but it may be a good way to validate such user-submitted data.

Best,
Hans

Powered by GitHub Issue Mirror