API units: 5 or 25. A page of up to 100 records uses 5 units. A page over 100 records uses 25 units. The default page size is 1,000, so a request without a page size uses 25 units.

This endpoint fetches analytics data on a per-journey basis. One record is returned per user journey, each of which may or may not yet be complete.

Data can be returned in JSON or CSV format. The columns in the CSV are fixed; not all values will be set for all events as some columns are specific to one event type.

Use the query parameters to filter the results by journey end date/time. Note some journeys span multiple days, and journeys from previous days may change if the user continues them into the next day, thus causing them to appear in the next days journey data. This is more of a concern for large authenticated services supporting save & come back later, than it is for smaller anonymous services that must be completed in one sitting.

Results are paginated, meaning the API endpoint will provide the first page of results along with the number of pages. Your application can then call the endpoint again to retrieve subsequent results pages.

Endpoint and parameters

GET /api/analytics-journeys/{libraryId}/{serviceId}

Parameter	Description	Mandatory
libraryId	The ID of the library of the service from which to retrieve journey analytics	yes
serviceId	The service ID of the service from which to retrieve journey analytics	yes

Query parameters

Parameter	Description	Mandatory
format	The output format to use in the response body, set to json or csv	yes
fromDate	The first event date to return data for (inclusive), in the format yyyy-mm-dd	yes
toDate	The last event date to return data for (inclusive), in the format yyyy-mm-dd	yes
hour	Restrict the result to one completed hour (0–23). Use only when fromDate and toDate are the same. For today, the hour must be earlier than the current hour. If omitted for today, Govforms returns data only up to the start of the current hour.	no
page	The page of results to fetch. If omitted, page 1 is assumed. The response body will include the number of pages to fetch; if over 1 then the endpoint should be called again with this parameter set to each subsequent page number to retrieve all result pages.	no
pageSize	Number of results per page, from 1 to 1000. Defaults to 1000; larger values are capped at 1000.	no
submissionRef	If specified, only events for the specified submission reference will be returned.	no
csvHeader	If format is set to csv, this parameter controls the header row to output. Set to on to include field names in the header row. Set to none to not include a header row in the output. Defaults to on.	no
csvHeaderFields	If format is set to csv, optionally set this to specify which fields should be included in the output, separated by commas. The provided values are compared against the CSV header titles for each field and so depend upon the csvHeader setting. The provided field columns will always be present in the order specified and no additional columns will be added.	no
excelMode	If format is set to csv, set this to on to wrap all values that are under 200 characters in ="value" to prevent Excel from attempting to auto-transform numbers and dates. For raw CSV feeds not intended for display in Excel, set to off. Defaults to off.	no

Authentication: send GovformsApiKey <key-id>:<key-secret> in the Authorization header. Substitute credentials from your secrets manager; never copy a live key into documentation, source control or logs.

Examples

Request Headers

Header name	value
Authorization	GovformsApiKey <key-id>:<key-secret>

JSON mode example:

Request URL

GET https://qa.cloud.govforms.uk/api/analytics-journeys/demo-library/demo-service-1?format=json&fromDate=2023-03-18&toDate=2023-03-18

  Response Headers

Header name	value
Content-Type	application/json

Response body

{
  "totalResults": 1,
  "totalResultsPages": 1,
  "resultsPage": 1,
  "results": [
    {
      "submissionId": "PGEE-EE2H-3Y67",
      "userId": "anon-c2305120-1a15-441d-90a8-b4246a9b8e71",
      "userEmail": null,
      "journeyStart": "2023-03-17T23:57:53.249+00:00",
      "journeyEnd": "2023-03-18T00:02:41.267+00:00",
      "journeyDayOfWeek": 6,
      "timeSpentOnPages": [
        {
          "pageNum": 1,
          "pageName": "About this service",
          "timeSpentSeconds": 0.909
        },
        {
          "pageNum": 2,
          "pageName": "Do you meet the requirements for this form?",
          "timeSpentSeconds": 35.86
        },
        {
          "pageNum": 3,
          "pageName": "You cannot continue if you do not meet the requirements",
          "timeSpentSeconds": 1200
        }
      ],
      "activeTimeInJourneySeconds": 1236.769,
      "isComplete": false,
      "numSuccessPageHits": 4,
      "numErrorPageHits": 0,
      "dropOutPageName": "You cannot continue if you do not meet the requirements",
      "dropOutPageNum": 3,
      "dropOutPageType": "exitPage",
      "validationErrors": [],
      "userAgentDetails": {
        "browser": {
          "name": "Microsoft Edge",
          "version": "110.0.1587.41"
        },
        "os": {
          "name": "Windows",
          "version": "NT 10.0",
          "versionName": "10"
        },
        "platform": {
          "type": "desktop"
        },
        "engine": {
          "name": "Blink"
        }
      },
      "taggedFieldData": {
        "doYouMeetTheRequirementsForThisForm": "No"
      }
    }
  ]
}

 

CSV mode example: Request URL

GET https://qa.cloud.govforms.uk/api/analytics-journeys/demo-library/demo-service-1?format=csv&fromDate=2023-03-18&toDate=2023-03-18

  Response headers

Header name	value
Content-Type	text/csv
Govforms-Total-Results	1
Govforms-Total-Results-Pages	1
Govforms-Results-Page	1

Response body

"submissionId","userId","userEmail","journeyStart","journeyEnd","journeyDayOfWeek","timeSpentOnPages-pageNum","timeSpentOnPages-pageName","timeSpentOnPages-timeSpentSeconds","activeTimeInJourneySeconds","isComplete","activeTimeInJourneySeconds", "isComplete", "numSuccessPageHits", "numErrorPageHits", "dropOutPageName", "dropOutPageNum", "dropOutPageType","validationErrors-timestamp","validationErrors-pageNum","userAgentDetails-browser-name","userAgentDetails-browser-version","userAgentDetails-os-name","userAgentDetails-os-version","userAgentDetails-os-versionName","userAgentDetails-platform-type","userAgentDetails-engine-name","taggedFieldData-fieldId","taggedFieldData-fieldValue"
"PGEE-EE2H-3Y67","anon-c2305120-1a15-441d-90a8-b4246a9b8e71",null,"2023-03-17T23:57:53.249+00:00","2023-03-18T00:02:41.267+00:00","6","1|2|3","About this service|Do you meet the requirements for this form?|You cannot continue if you do not meet the requirements","0.909|35.86|1200","1236.769","false","1236.769","false","4","0","You cannot continue if you do not meet the requirements","3","exitPage","","","Microsoft Edge","110.0.1587.41","Windows","NT 10.0","10","desktop","Blink","doYouMeetTheRequirementsForThisForm","No"

 

---