Introduction

The Eco-Visio API is an interface allowing developers to access the data from your Eco-Visio domain. The interface is stable and currently used by several of our applications. Please note however that changes may be made occasionally for continuous improvement.

API Endpoint

https://apieco.eco-counter-tools.com/api/

Getting Started

If you wish to subscribe to our API, please contact us. You will be given credentials allowing you to access your data through the Eco-Visio API.

Feel free to contact our sales team from our Website.

Rate limiting

There are currently no rate limits on API requests however we operate a fair usage policy and reserve the right to cut off temporarely access to any applications seen to abuse this policy. Eco-Counter considers that a fair usage is below 100 requests per minute or 5000 requests per day.

Authentication

You can access your data by using a token with each request made through the API. You will be given a default token with unlimited validity time. Eco-Visio API uses OAuth2 Client Credentials Flow as an authentication protocol. With this protocol, your application sends its own credentials (Client ID and Client Secret) to an endpoint on Eco-Counter’s server that is set up to generate an access token. If the credentials are valid, the endpoint sends back an access token to your application. Please note that you can also manage your API token directly from the API Manager.

Getting a Token from the API Manager

You can manage your API token from the “Token” page on our API Manager. From this page you can create or delete tokens, as well as protect them by limiting them to specific domains or validity times.

API Manager

https://apiadmin.eco-counter-tools.com/store

Acquiring a Token via System Request

If you wish to get a token from our Authorization Server, you can make a POST request using the parameters below.

Parameters
hash	string hash is base64 encoded client id:client secret value.

Response Attributes
scope	string Scope of the token. The value is "default"
token_type	string Authorization token type
expires_in	number Remaining validity time in seconds
access_token	string Token value

Request Example

curl -v -X POST https://apieco.eco-counter-tools.com/token \
     -H "Authorization: Basic hash" \
     -H "Content-Type:application/x-www-form-urlencoded" \ 
     -k -d "grant_type=client_credentials"

Response Example

                        
{
	"scope": "am_application_scope default",
	"token_type": "bearer",
	"expires_in": 3600,
	"access_token": "b3f5db903fsd6c23d9e4ed1d16ab69e0"
}

Using Your Token

For each request you make to the API, you must pass your Token in the http header.

Request Example

curl -X GET "https://apieco.eco-counter-tools.com/api/1.0/counter" \
     -H "Accept: application/json" \
     -H "Authorization: Bearer d682ce9a9b66886d539e4f1f8f329e7"

Counting Site

The word "counting site" should not be confused with the word "counter". The counter is the unit itself, while the counting site is where the unit is installed. In Eco-Visio, the counter is represented by its serial number, while the counting site is represented by each item you see in your dashboard, which is in turn given a location name, coordinates, a picture, etc. While counters can move, the counting sites are what will retain the relevant data. With this request you get information allowing to identify or describe your counting sites.

Attributes
id	int Unique ID generated by the server
name	string Name of the counting site
customSiteId	string Custom site identifier
domain	string Name of the domain
domainId	int Identifier of the domain
latitude	double Geographic coordinates in decimal degrees
longitude	double Geographic coordinates in decimal degrees
userType	int {1: pedestrian, 2: bicycle, 3: horse, 4: car, 5: bus, 6: minibus, 7: undefined, 8: motorcycle, 9: kayak, 13: e-scooter, 14: truck}
timeZone	string
interval	int Data recording interval (15 or 60 minutes)
sens	int Direction detection information. {1: IN direction, 2: OUT direction, 5: No direction distinction}
installationDate	date First Counter Installation Date. Format: ISO 8601
firstData	date Date of First Data. May differ from installationDate because reconstructed or missing data. Format: ISO 8601
photos	string array URLs of the photos of the counting site
counter	string Serial number of the counter currently linked to the counting site
type	string Type of site ("real ou virtual")
visible	boolean Visibility of the site
channels	site array List of the channels of the counting site (i.e.: user types, directions, etc.)
tags	tag array List of the tags of the counting site
attributes	attribute map Map of attributes of the counting site

Example

                        
{
  "id": 123456789,
  "name": "Avenue des Champs-Elysées",
  "customSiteId": "123A456B789C",
  "domain": "Eco-Counter",
  "domainId": 123,
  "latitude": 48.867834,
  "longitude": 2.313706, 
  "userType": 2,
  "timezone": "(UTC+01:00) Europe/Paris;DST",
  "interval": 60,
  "sens": 0,
  "installationDate": "2014-03-15T00:00:00+0100",
  "firstData": "2014-03-15T00:00:00+0100",
  "photos": [
      "https://eco-visio.net/mywonderfullsite.jpg"
  ],
  "counter": "ABC123456",
  "type": "real",
  "visible": true,
  "channels": [],
  "tags": []
  "attributes": {}
}

Counter

With this request the user gets information allowing them to identify or describe the counters. The word "counter" should not be confused with the word "counting site". The counter is the unit itself, while the counting site is where the unit is installed. In Eco-Visio, the counter is represented by its serial number, while the counting site is represented by each item you see in your dashboard, which is in turn given a location name, coordinates, a picture, etc.

Attributes
serial	string Counter serial number
gsm	string Modem number
iccid	string ICCID number
articleCode	string Eco-Counter product code
softVersion	string
hardVersion	string
expeditionDate	date Format: ISO 8601

Example

                        
{
  "serial": "ABC123456",
  "gsm": "+33123456789",
  "iccid": "1231542318421515",
  "articleCode": "AB123456",
  "softVersion": 1.01, 
  "hardVersion": 1.23,
  "expeditionDate": "2008-07-29T00:00:00+0200"
}

Data

The word “Data” refers to the counting data produced by the counter and recorded to the counting site.

Attributes
date	date Deprecated. The attribute "date" is not ISO-8601 compliant. The timestamp is returned by the API in local timezone even if "+0000" indicates UTC datetime. Please, use the "isoDate" attribute instead.
isoDate	date Format ISO 8601. Date in local timezone with GMT offset. The offset format is basic (example : "+0200") and "+0000" is not replaced by "Z"
counts	int Number of people counted
status	int Status of the data {0: raw / 1: excluded / 2: deleted / 4: modified / 8: validated / 16: certified} Note that these statuses can be combined. Example: status 12 = modified (4) and validated (8)

Example

                        
{
  "date": "2015-01-05T00:00:00+0000",
  "isoDate": "2015-01-05T00:00:00+0500",
  "counts": 20,
  "status": 0
}

Tag

The word “Tag” refers to a grouping of counting sites, made by users. This grouping has a name, and a color to distinguish them.

Attributes
id	int Identifier of the tag
name	string Name of the tag
description	string Description of the tag
color	string Color of the tag (Hex format, example : #24b7d2)
domain	string Name of the domain
domainId	int Identifier of the domain
username	string Username of the owner of the tag

Example

                        
{
  "id": 123456,
  "name": "my tag",
  "description": "my description",
  "color": "#24b7d2",
  "domain": "my domain",
  "domainId": 123,
  "username": "username_1"
}

Listing the Counting Sites

This request permits the user to obtain a list of the counting sites.

Parameters
domain_id	string Restrict results to one domain Optionnal
attributes	string Get custom attributes values (default: false) Optionnal

Path

GET /site

Request Example

curl -G https://apieco.eco-counter-tools.com/api/1.0/site \ 
     -H "Accept: application/json" \
     -H "Authorization: Bearer d682ce9a9b66886d539e4f1f8f329e7"

Response Example

                        
HTTP/1.1 200 OK
Content-Type:application/json;charset=UTF-8
[
	{
	  "id": 123456789,
	  "name": "Avenue des Champs-Elysées",
	  "customSiteId": "123A456B789C",
	  "domain": "Eco-Counter",
	  "domainId": 123,
	  "latitude": 48.867834,
	  "longitude": 2.313706, 
	  "userType": 2,
	  "timezone": "(UTC+01:00) Europe/Paris;DST",
	  "interval": 60,
	  "sens": 0,
	  "installationDate": "2014-03-15T00:00:00+0100",
	  "firstData": "2014-03-15T00:00:00+0100",
	  "photos": [
	      "https://eco-visio.net/mywonderfullsite.jpg"
	  ],
	  "counter": "ABC123456",
	  "type": "real",
	  "visible": true,
	  "channels": [],
	  "tags": [],
	  "attributes": {}
	},
	{...},
	{...}
]

Retrieving a Specific Counting Site

This request permits the user to obtain counting site information based on its identification number.

Parameters
id	int Identifier of the counting site
attributes	string Get custom attributes values (default: false) Optionnal

Path

GET /site/{id}

Request Example

curl -G https://apieco.eco-counter-tools.com/api/1.0/site/123456789 \ 
     -H "Accept: application/json" \
     -H "Authorization: Bearer d682ce9a9b66886d539e4f1f8f329e7"

Response Example

                        
HTTP/1.1 200 OK
Content-Type:application/json;charset=UTF-8
{
  "id": 123456789,
  "name": "Avenue des Champs-Elysées",
  "customSiteId": "123A456B789C",
  "domain": "Eco-Counter",
  "domainId": 123,
  "latitude": 48.867834,
  "longitude": 2.313706, 
  "userType": 2,
  "timezone": "(UTC+01:00) Europe/Paris;DST",
  "interval": 60,
  "sens": 0,
  "installationDate": "2014-03-15T00:00:00+0100",
  "firstData": "2014-03-15T00:00:00+0100",
  "photos": [
      "https://eco-visio.net/mywonderfullsite.jpg"
  ],
  "counter": "ABC123456",
  "type": "real",
  "visible": true,
  "channels": [],
  "tags": [],
  "attributes": {}
}

Obtaining a List of the Counters

This request permits the user to obtain a list of the counters.

Parameters
	No parameter

Path

GET /counter

Request Example

curl -G https://apieco.eco-counter-tools.com/api/1.0/counter \ 
     -H "Accept: application/json" \
     -H "Authorization: Bearer d682ce9a9b66886d539e4f1f8f329e7"

Response Example

                        
HTTP/1.1 200 OK
Content-Type:application/json;charset=UTF-8
[
	{
	  "serial": "ABC123456",
	  "gsm": "+33123456789",
	  "iccid": "1231542318421515",
	  "articleCode": "AB123456",
	  "softVersion": 1.01, 
	  "hardVersion": 1.23,
	  "expeditionDate": "2008-07-29T00:00:00+0200"
	},
	{...},
	{...}
]

Retrieving a Specific Counter

This request permits the user to obtain a counter based on its identifier.

Parameters
serialnumber	String Counter serial number

Path

GET /counter/{serialnumber}

Request Example

curl -G https://apieco.eco-counter-tools.com/api/1.0/counter/ABC123456 \ 
     -H "Accept: application/json" \
     -H "Authorization: Bearer d682ce9a9b66886d539e4f1f8f329e7"

Response Example

                        
HTTP/1.1 200 OK
Content-Type:application/json;charset=UTF-8
{
  "serial": "ABC123456",
  "gsm": "+33123456789",
  "iccid": "1231542318421515",
  "articleCode": "AB123456",
  "softVersion": 1.01, 
  "hardVersion": 1.23,
  "expeditionDate": "2008-07-29T00:00:00+0200"
}

Obtaining Count Data

This request allows to obtain data from a counter.

Parameters
id	int Counting Site ID
begin	date Data period start date (included) in ISO 8601 format. If no start date has been defined, the first data date will be used. Optionnal
end	date End of data period (excluded) in ISO 8601 format, excluded. If no end date has been defined, the last data date will be used. Optionnal
step	int Data interval. Permitted values: 15m / hour / day / week / month / year (default: hour) Optionnal
complete	boolean Replaces data holes with null values (default: true) Optionnal

Path

GET /data/site/{id}?[begin=...]&[end=...]&[step=...]&[complete=...]

Request Example

curl -G https://apieco.eco-counter-tools.com/api/1.0/data/site/123456789?begin=2015-01-01T00:00:00&end=2015-03-31T23:59:59&step=day \ 
     -H "Accept: application/json" \
     -H "Authorization: Bearer d682ce9a9b66886d539e4f1f8f329e7"

Response Example

                        
HTTP/1.1 200 OK
Content-Type:application/json;charset=UTF-8
[
	{
	  "date": "2015-01-01T00:00:00+0000",
	  "isoDate": "2015-01-01T00:00:00+0500",
	  "counts": 13,
	  "status": 0
	},
	{
	  "date": "2015-01-02T00:00:00+0000",
	  "isoDate": "2015-01-02T00:00:00+0500",
	  "counts": 18,
	  "status": 0
	},
	{
	  "date": "2015-01-03T00:00:00+0000",
	  "isoDate": "2015-01-03T00:00:00+0500",
	  "counts": 21,
	  "status": 0
	},
	{...},
	{...}
]

Listing the Tags

This request allows to obtain tags from a domain.

Parameters
domain_id	int Identifier of the domain Optionnal

Path

GET /tag?[domain_id=...]

Request Example

curl -G https://apieco.eco-counter-tools.com/api/1.0/tag?domain_id=123 \
     -H "Accept: application/json" \
     -H "Authorization: Bearer d682ce9a9b66886d539e4f1f8f329e7"

Response Example

                        
HTTP/1.1 200 OK
Content-Type:application/json;charset=UTF-8
	{
	  "id": 123456,
	  "name": "my tag 1",
	  "description": "my description 1",
	  "color": "#24b7d2",
	  "domainId": 123,
	  "domain": "my domain 1",
	  "username": "username_1"
	},
	{
	  "id": 123457,
	  "name": "my tag 2",
	  "description": "my description 2",
	  "color": "#6ef295",
	  "domainId": 123,
	  "domain": "my domain 1",
	  "username": "username_1"
	},
	{
	  "id": 123458,
	  "name": "my tag 3",
	  "description": "my description 3",
	  "color": "#87888a",
	  "domainId": 123,
	  "domain": "my domain 1",
	  "username": "username_1"
	},
	{...},
	{...}
]