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.

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

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.

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

Example

                        
{
  "id": 123456789,
  "name": "Avenue des Champs-Elysées",
  "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": []
}
							
						

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)

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",
  "domainId": 123,
  "username": "username_1"
}
							
						

Listing the Counting Sites

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

No parameter

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",
	  "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": []
	},
	{...},
	{...}
]
							
						

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

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",
  "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": []
}
							
						

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 or Channel 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",
	  "counts": 13,
	  "status": 0
	},
	{
	  "date": "2015-01-02T00:00:00+0000",
	  "counts": 18,
	  "status": 0
	},
	{
	  "date": "2015-01-03T00:00:00+0000",
	  "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,
	  "username": "username_1"
	},
	{
	  "id": 123457,
	  "name": "my tag 2",
	  "description": "my description 2",
	  "color": "#6ef295",
	  "domainId": 123,
	  "username": "username_1"
	},
	{
	  "id": 123458,
	  "name": "my tag 3",
	  "description": "my description 3",
	  "color": "#87888a",
	  "domainId": 123,
	  "username": "username_1"
	},
	{...},
	{...}
]