Counts API Migration

As part of our API deprecation plan, we are proposing that users move to the /countline/counts endpoint from the legacy /counts endpoint. This guide explains the differences between the two endpoints to help support with migration.

1 Authentication
- 1.1 Migration Required
2 Parameters
- 2.1 Migration required
3 Response Body
4 More Information

Authentication

Please make sure you are using the API Keys method of authentication. This has a number of advantages to the legacy API token method:

No authorisation call required — there’s no requirement to use the /get-token endpoint or equivalent
No token expiry — no need to refresh a token
Generate your own API Key
Per application keys

Migration Required

Remove any usage of the /get-token or /refresh-token endpoints. First-time only: generate and save an API Key from your User Management area.

Change the Headers:

Remove the Authorization key: value pair from the header
Add the x-vivacity-api-key: {{api-key}} value pair to the header

Parameters

The new /countline/counts endpoint has some renamed parameters and also new parameters more consistent with our other APIs.

Legacy `/counts` endpoint	`/countline/counts` endpoint	Notes

Legacy `/counts` endpoint	`/countline/counts` endpoint	Notes
`countline`	`countline_ids`	This is now a required field in the new endpoint. Use the `countline/metadata` endpoint to retrieve a list of accessible countlines
`class`	`classes`
`timeFrom`	`from`	Same format (ISO 8601)
`timeTo`	`to`	Same format (ISO 8601)
`includeZeroCounts`	`fill_zeros`
	`time_bucket`
	`convert_pcus`

Migration required

Renaming of parameters.
Addition of countline_ids to query.

Response Body

The response body contains the same data, in a slightly different format. The new format is more scalable when designing an application to use it, using arrays at a higher level, and less nesting. It is in a more similar format to our other current APIs.

Legacy `/counts` endpoint	`/countline/counts` endpoint

Legacy /counts endpoint

/countline/counts endpoint

{
    "16666": {
        "2024-02-01T09:00:00.000Z": {
            "from": "2024-02-01T09:00:00.000Z",
            "to": "2024-02-01T09:05:00.000Z",
            "counts": [
                {
                    "class": "car",
                    "countIn": 197,
                    "countOut": 526
                },
                {
                    "class": "pedestrian",
                    "countIn": 18,
                    "countOut": 9
                }
            ]
        },
        "2024-02-01T09:05:00.000Z": {
            "from": "2024-02-01T09:05:00.000Z",
            "to": "2024-02-01T09:10:00.000Z",
            "counts": [
                {
                    "class": "car",
                    "countIn": 171,
                    "countOut": 277
                },
                {
                    "class": "pedestrian",
                    "countIn": 5,
                    "countOut": 1
                }
            ]
        },
        "2024-02-01T09:10:00.000Z": {
            "from": "2024-02-01T09:10:00.000Z",
            "to": "2024-02-01T09:15:00.000Z,
            "counts": [
                {
                    "class": "car",
                    "countIn": 192,
                    "countOut": 235
                },
                {
                    "class": "pedestrian",
                    "countIn": 7,
                    "countOut": 6
                }
            ]
        }
    }
}

{
  "16666": [
    {
      "from": "2024-02-01T09:00:00.000Z",
      "to": "2024-02-01T09:05:00.000Z",
      "anti_clockwise": {
        "car": 526,
        "pedestrian": 9
      },
      "clockwise": {
        "car": 197
        "pedestrian": 18
      }
    },
    {
      "from": "2024-02-01T09:05:00.000Z",
      "to": "2024-02-01T09:10:00.000Z",
      "anti_clockwise": {
        "car": 277,
        "pedestrian": 1
      },
      "clockwise": {
        "car": 171,
        "pedestrian": 5
      }
    },
    {
      "from": "2024-02-01T09:10:00.000Z",
      "to": "2024-02-01T09:15:00.000Z",
      "anti_clockwise": {
        "car": 235,
        "pedestrian": 6
      },
      "clockwise": {
        "car": 192,
        "pedestrian": 7
      }
    }
  ]
}

The legacy endpoint refers to countIn and countOut. This corresponds to the clockwise and anti_clockwise directions in the new endpoint. This is more consistent, for example when countlines are drawn vertically in image space, and refers to the direction cars are crossing the countline with reference to the end of the countline on the LHS/bottom of the image space.