API Export Data Service v1

(Dernière mise à jour le 22 décembre 2020)


REMARQUE POUR LES UTILISATEURS D’API BEACON AU CANADA

Les données de votre service sont en cours de transfert ou ont déjà été transférées au Canada conformément à la réglementation canadienne sur les données transfrontalières. Par conséquent, si vous vous connectez à BEACON via beaconama.ca, vous devez modifier tous vos appels DE L’API pour gérer des points de terminaison sur api.beaconama.ca.

Par exemple, remplacez

https://api.beaconama.net/v1/eds/read/

par

https://api.beaconama.ca/v1/eds/read/

Cette modification affecte l’ensemble des appels DE L’API de point de terminaison pour les services se connectant à beaconama.ca.


L’API Export Data Services v1 API offre les méthodes suivantes pour prendre en charge la fonctionnalité d’exportation des données.

/v1/eds/flow

Méthode Description
POST Publiez une requête pour exporter les données et relevés de débit agrégés à une date de début et de fin.

/v1/eds/consumption

Méthode Description
POST Publiez une requête pour exporter la consommation totale agrégée.

/v1/eds/formatc

Méthode Description
POST Publiez une requête pour exporter les données de lecture de facturation les plus récentes à l’aide de fichiers d’entrée au Format C.

/v1/eds/range

Méthode Description
POST Publiez une requête pour exporter les données de débit sur une plage de dates.

/v1/eds/read

Méthode Description
POST Publiez une requête pour exporter les données de lecture de facturation les plus récentes.

/v1/eds/exception_range

Méthode Description
POST Publiez une requête pour exporter une liste d’alertes issues des compteurs, encodeurs et points de terminaison ainsi que les dates de début et de fin des alertes.

/v1/eds/status{edsUUID}

Méthode Description
GET Récupère l’état actuel du traitement de l’exportation, y compris une URL pour télécharger les résultats d’exportation, lorsqu’ils sont disponibles.

BEACON Export Data Services

POST /v1/eds/flow

 

Soumet une requête pour récupérer les données et lectures de débit agrégées d’exportation à une date de début et de fin. Voir le schéma des processus de l’API BEACON Export Data Services.

Remarque : l’en-tête Content-Type doit être défini sur application/x-www-form-urlencoded dans la requête.

Paramètres :

startDate(erreur)Date

Date de la requête;chaîne entre guillemets ISO 8601, par exemple « 2015-08-23T22:06:09Z ».

La valeur par défaut du code est 23:59:59 dans le fuseau horaire du compteur si l’heure n’est pas fournie.

Nom du paramètre Requis Type Description
buildingType Texte Étiquette (par exemple, « commerce », « restaurant », « appartements ») utilisée pour filtrer dans BEACON Monitor.
continuousFlowExpected Texte Yes/No.
dhsCode Texte Code du département des services de santé utilisé pour identifier les sources d’eau.
district Texte Un identifiant unique pour le district.
endDate (erreur) Date Date de la requête;chaîne entre guillemets ISO 8601, par exemple « 2015-08-23T22:06:09Z ».

La valeur par défaut du code est 23:59:59 dans le fuseau horaire du compteur si l’heure n’est pas fournie.

funding Texte Étiquette pour le filtrage sur la page Monitor (Surveillance) de BEACON.
hasEndpoint Booléen true pour limiter les résultats aux compteurs qui ont un point de terminaison, false pour les compteurs qui n’ont pas de point de terminaison, ou omettent d’inclure les deux.
headerColumns Texte Liste des noms de colonnes séparées par des virgules à inclure dans la sortie :

• Account_ID
• Endpoint_SN
• Flow
• Flow_Unit
• Location_Area
• Location_Bathrooms
• Location_Building_Number
• Location_Building_Type
• Location_DHS_Code
• Location_District
• Location_Funding
• Location_ID
• Location_Irrigated_Area
• Location_Irrigation
• Location_Main_Use
• Location_Pool
• Location_Population
• Location_Site
• Location_Water_Type
• Location_Year_Built
• Meter_ID
• Point_1_Read
• Point_1_Read_Time
• Point_2_Read
• Point_2_Read_Time
• Portal_ID
• Read_Unit
• Register_Number
• Service_Point_ID
• Service_Point_Timezone

limit Nombre Limitent le nombre de compteurs pour lesquels des données sont renvoyées, utilisés pour la pagination. La valeur par défaut est de 25 000. Doit être comprise entre 1 et 25 000.
mainUse Texte Étiquette pour le filtrage sur la page Monitor (Surveillance) de BEACON.
meterID Texte Un identifiant pour le compteur; peut être fourni plusieurs fois.
meterSize Texte Taille numérique du compteur. (5/8 = 0,625, 3/4 = 0,75, 1 1/2 = 1,5; etc.)
lastMeterID Texte Identifiant facultatif utilisé pour la pagination des résultats de compteur.
outputFormat Texte Format de sortie à utiliser :
• csv : produit des fichiers CSV simples avec des chaînes entre guillemets si nécessaire (format par défaut).
• json : produit un JSON pour une utilisation par d’autres programmes.
csvSeparator Texte Séparateur de colonnes à utiliser. Saisissez l’une des options suivantes :

, ; : | ~

Par exemple un caractère unique pour la virgule (,) , le point-virgule (;), les deux-points (:), la barre verticale (|) ou le tilde (~).

csvQuotingOption Texte Incluez ou excluez les guillemets autour de tous les champs exportés dans un fichier CSV :

  • all : incluez des guillemets autour de tous les champs.
  • none : excluez les guillemets.

Pour plus d’informations sur l’utilisation des guillemets, cliquez ici.

route Texte L’identificateur du tracé ou du journal auquel le service facturé appartient.
servicePointClassCode Texte L’identifiant pour la classification/catégorie de facturation de ce point de raccordement dans le système de facturation, comme résidentiel, commercial, irrigation, etc.
servicePointCycle Texte Un identificateur utilisé pour désigner le nom du cycle de facturation.
site Texte Étiquette (par exemple « Campus nord », « Centre-ville ») pour filtrer dans BEACON Monitor.
unit Texte Unité utilisée pour présenter les données de débit :

• acrefeet
• ccf
• cubicfeet
• cubicmeter
• gallons (default)
• liter

waterType Texte Étiquette (par exemple, « chaude », « froide », « potable », « recyclée ») pour filtrer dans BEACON Monitor.

POST EDS::Request

POST /v1/eds/flow

# Utilisez ces paramètres pour publier une requête pour exporter
# des données et des lectures de débit agrégés à une date de début et à une date de fin.
#
servicePointCycle=11111
startDate=2016-02-01T00:00:00Z
endDate=2016-02-29T23:59:59Z
headerColumns=Account_ID,Meter_ID,Flow
#

curl

# Utilisez cette déclaration cURL pour publier une requête pour exporter# des données et des lectures de débit agrégés à une date de début et à une date de fin.
#
curl 
-X POST -uusername:password \
-H "Content-Type: application/x-www-form-urlencoded" \
-d servicePointCycle=11111 \
-d district=las \
-d startDate=2016-02-01T00:00:00Z \
-d endDate=2016-02-29T23:59:59Z \
-d headerColumns=Account_ID,Meter_ID,Flow \ 
https://api.beaconama.net/v1/eds/flow
#

POST EDS::Response

{    
"edsUUID": 
"70FC1B71-F0C3-4950-885C-A635E7C4E034",    
"statusUrl": 
"/v1/eds/status/70FC1B71-F0C3-4950-885C-A635E7C4E034"}

Response

Renvoie un objet EDSNew.

202 Accepté – La requête EDS a été soumise correctement et il est possible de suivre l’état sur l’emplacement statusUrl.

POST /v1/eds/consumption

Soumet une requête pour récupérer des données de consommation agrégées à une date de début et à une date de fin.

Remarque : l’en-tête Content-Type doit être défini sur application/x-www-form-urlencoded dans la requête.

Paramètres :

Nom du paramètre Requis Type Description
endDate (erreur) Date Date de la requête;chaîne entre guillemets ISO 8601, par exemple « 2015-08-23T22:06:09Z ».

La valeur par défaut du code est 23:59:59 dans le fuseau horaire du compteur si l’heure n’est pas fournie.

hasEndpoint Booléen true pour limiter les résultats aux compteurs qui ont un point de terminaison, false pour les compteurs qui n’ont pas de point de terminaison, ou omettent d’inclure les deux.
headerColumns (erreur) Texte Liste des noms de colonnes séparées par des virgules à inclure dans la sortie :

Day_of_Week
Flow
Flow_Time
Flow_Unit
Num_Meters

Num_Meters compte le nombre total de compteurs avec un débit > 0.

limit Nombre Limitent le nombre de compteurs pour lesquels des données sont renvoyées, utilisés pour la pagination. La valeur par défaut est de 25 000. Doit être comprise entre 1 et 25 000.
buildingType Texte Étiquette (par exemple, « commerce », « restaurant », « appartements ») utilisée pour filtrer dans BEACON Monitor.
dhsCode Texte Code du département des services de santé utilisé pour identifier les sources d’eau.
district Texte Un identifiant unique pour le district.
funding Texte Étiquette pour le filtrage sur la page Monitor (Surveillance) de BEACON.
mainUse Texte Étiquette pour le filtrage sur la page Monitor (Surveillance) de BEACON.
site Texte Étiquette (par exemple « Campus nord », « Centre-ville ») pour filtrer dans BEACON Monitor.
waterType Texte Étiquette (par exemple, « chaude », « froide », « potable », « recyclée ») pour filtrer dans BEACON Monitor.
continuousFlowExcepted Texte Yes/No.
meterID Texte Un identifiant pour le compteur; peut être fourni plusieurs fois.
meterSize Texte Taille numérique du compteur. (5/8 = 0,625, 3/4 = 0,75, 1 1/2 = 1,5; etc.)
lastMeterID Texte Identifiant facultatif utilisé pour la pagination des résultats de compteur.
outputFormat Texte Format de sortie à utiliser :

• csv : produit des fichiers CSV simples avec des chaînes entre guillemets si nécessaire (format par défaut).

• json : produit un JSON pour une utilisation par d’autres programmes.

csvSeparator Texte Séparateur de colonnes à utiliser. Saisissez l’une des options suivantes :

, ; : | ~

Par exemple un caractère unique pour la virgule (,) , le point-virgule (;), les deux-points (:), la barre verticale (|) ou le tilde (~).

csvQuotingOption Texte Incluez ou excluez les guillemets autour de tous les champs exportés dans un fichier CSV :

  • all : incluez des guillemets autour de tous les champs.
  • none : excluez les guillemets.

Pour plus d’informations sur l’utilisation des guillemets, cliquez ici.

resolution Texte Niveau d’agrégation :

  • daily (par défaut)
  • quarter_hourly
  • hourly
  • monthly
servicePointClassCode Texte L’identifiant pour la classification/catégorie de facturation de ce point de raccordement dans le système de facturation, comme résidentiel, commercial, irrigation, etc.
servicePointCycle Texte Un identificateur utilisé pour désigner le nom du cycle de facturation.
route Texte L’identificateur du tracé ou du journal auquel le service facturé appartient.
startDate (erreur) Date Date de la requête;chaîne entre guillemets ISO 8601, par exemple « 2015-08-23T22:06:09Z ».

La valeur par défaut du code est 23:59:59 dans le fuseau horaire du compteur si l’heure n’est pas fournie.

tolerance Nombre Le nombre d’heures auxquelles revenir en arrière pour la dernière lecture. Doit être >= 24.
unit Texte Unité utilisée pour présenter les données de débit :

• acrefeet
• ccf
• cubicfeet
• cubicmeter
• gallons (par défaut)
• liter

POST EDS::RequestPOST /v1/eds/consumption

# Utilisez ces paramètres pour publier une requête pour exporter# la consommation agrégée pour une date de début et une date de fin avec une tolérance spécifique.
#servicePointCycle=11111startDate=2016-02-01T00:00:00ZendDate=2016-02-29T23:59:59Ztolerance=72headerColumns=Flow,Flow_Time,Flow_Unit #

curl

# Utilisez cette déclaration cURL pour publier une requête pour exporter# les données de consommation agrégée à une date de début et à une date de fin avec une tolérance spécifique.
#curl -X POST -uusername:password \-H "Content-Type: application/x-www-form-urlencoded" \-d servicePointCyce=11111 \-d startDate=2016-02-01T00:00:00Z \-d endDate=2016-02-29T23:59:59Z \-d tolerance=72 \-d headerColumns=Flow,Flow_Time,Flow_Unit \https://api.beaconama.net/v1/eds/consumption#

POST EDS::Response

{    "edsUUID": "70FC1B71-F0C3-4950-885C-A635E7C4E034",    "statusUrl": "/v1/eds/status/70FC1B71-F0C3-4950-885C-A635E7C4E034"}

Response

ReturnsEDSNew object.

202 Accepté – La requête EDS a été soumise correctement et il est possible de suivre l’état sur l’emplacement statusUrl.

• l’en-tête d’emplacement renvoie vers statusUrl

• l’en-tête d’emplacement renvoie vers statusUrl

POST /v1/eds/formatc

 

Publiez une requête pour exporter les données de lecture de facturation les plus récentes à l’aide d’un fichier d’entrée au Format C dans la tolérance indiquée. Ce point de terminaison de l’API utilise les informations du compteur et du compte du fichier fourni comme filtres. Les données renvoyées seront au Format C, conformément au fichier d’origine, plutôt qu’au format CSV.

Remarque : l’en-tête Content-Type doit être défini sur application/x-www-form-urlencoded dans la requête.

Paramètres :

Nom du paramètre Requis Type Description
data (erreur) File Le fichier d’entrée au Format C à partir duquel extraire les informations du compteur et du compte.
date (erreur) Date Date de la requête;chaîne entre guillemets ISO 8601, par exemple « 2015-08-23T22:06:09Z ».

La valeur par défaut du code est 23:59:59 dans le fuseau horaire du compteur si l’heure n’est pas fournie.

tolerance (erreur) Nombre Le nombre d’heures auxquelles revenir en arrière pour la dernière lecture. Doit être >= 24.

POST EDS::Request

POST /v1/eds/formatc

# Utilisez ces paramètres pour publier une requête pour exporter # les données de lecture de facturation les plus récentes à l’aide d’un fichier au Format C, # dans la tolérance indiquée.
#data=$HOME/Desktop/my-format-c-data.txtdate=2015-08-23T22:06:09Ztolerance=72#

curl

# Utilisez cette déclaration cURL pour publier une requête pour exporter # les données de lecture de facturation les plus récentes à l’aide d’un fichier au Format C, # dans la tolérance indiquée.
#curl -uusername:password \-H "Content-Type: application/x-www-form-urlencoded" \-F data=@$HOME/Desktop/my-format-c-data.txt \-F date=2015-08-23T22:06:09Z \-F tolerance=72 \https://api.beaconama.net/v1/eds/formatc#

POST EDS::Response

{
    "edsUUID": "70FC1B71-F0C3-4950-885C-A635E7C4E034",
    "statusUrl": "/v1/eds/status/70FC1B71-F0C3-4950-885C-A635E7C4E034"
}

Response

Renvoie un objet EDSNew.

202 Accepté – La requête EDS a été soumise correctement et il est possible de suivre l’état sur l’emplacement statusUrl.

• l’en-tête d’emplacement renvoie vers statusUrl

POST /v1/eds/range

Soumet une requête pour exporter les données de débit sur une plage de dates.

Remarque : l’en-tête Content-Type doit être défini sur application/x-www-form-urlencoded dans la requête.

Paramètres :

startDate(erreur)Date

Date de la requête;chaîne entre guillemets ISO 8601, par exemple « 2015-08-23T22:06:09Z ».

La valeur par défaut du code est 23:59:59 dans le fuseau horaire du compteur si l’heure n’est pas fournie.

Nom du paramètre Requis Type Description
buildingType Texte Étiquette (par exemple, « commerce », « restaurant », « appartements ») utilisée pour filtrer dans BEACON Monitor.
continuousFlowExpected Texte Yes/No.
dhsCode Texte Code du département des services de santé utilisé pour identifier les sources d’eau.
district Texte Un identifiant unique pour le district.
endDate (erreur) Date Date de la requête;chaîne entre guillemets ISO 8601, par exemple « 2015-08-23T22:06:09Z ».

La valeur par défaut du code est 23:59:59 dans le fuseau horaire du compteur si l’heure n’est pas fournie

funding Texte Étiquette pour le filtrage sur la page Monitor (Surveillance) de BEACON.
hasEndpoint Booléen true pour limiter les résultats aux compteurs qui ont un point de terminaison, false pour les compteurs qui n’ont pas de point de terminaison, ou omettent d’inclure les deux.
headerColumns Texte Liste des noms de colonnes séparées par des virgules à inclure dans la sortie :

• Account_Full_Name
• Account_ID
• Backflow (gal/30 days)
• Battery Level
• Billing_Address_Line1
• Billing_Address_Line2
• Billing_Address_Line3
• Billing_City
• Billing_State
• Billing_Zip
• Connector Type
• Current Leak Rate (gal/hr)
• Current Leak Start Date
• Dials
• Encoder_Read
• Endpoint Status
• Endpoint_SN
• Endpoint_Type
• Estimated Flag
• Flow
• Flow_Time
• Flow_Unit
• Last Comm. Time
• Last Gateway Id
• Location_Address_Line1
• Location_Area
• Location_Bathrooms
• Location_Building_Number
• Location_Building_Type
• Location_City
• Location_DHS_Code
• Location_District
• Location_Funding
• Location_ID
• Location_Irrigated_Area
• Location_Irrigation
• Location_Main_Use
• Location_Name
• Location_Pool
• Location_Population
• Location_Site
• Location_State
• Location_Water_Type
• Location_Year_Built
• Location_Zip
• Meter_ID
• Meter_Manufacturer
• Meter_Model
• Meter_SN
• Meter_Size
• Meter_Size_Desc
• Portal_Email
• Portal_ID
• Read
• Read_Method
• Read_Time
• Read_Unit
• Register_Number
• Register_Resolution
• Register_Unit_Of_Measure
• Service_Point_Class_Code
• Service_Point_Cycle
• Service_Point_ID
• Service_Point_Latitude
• Service_Point_Longitude
• Service_Point_Route
• Service_Point_Timezone
• Signal Strength

limit Nombre Limitent le nombre de compteurs pour lesquels des données sont renvoyées, utilisés pour la pagination. La valeur par défaut est de 10000. Doit être comprise entre 1 et 10000.
mainUse Texte Étiquette pour le filtrage sur la page Monitor (Surveillance) de BEACON.
meterID Texte Un identifiant pour le compteur; peut être fourni plusieurs fois.
meterSize Texte Taille numérique du compteur. (5/8 = 0,625, 3/4 = 0,75, 1 1/2 = 1,5; etc.)
lastMeterID Texte Identifiant facultatif utilisé pour la pagination des résultats de compteur.
outputFormat Texte Format de sortie à utiliser :
• csv : produit des fichiers CSV simples avec des chaînes entre guillemets si nécessaire (format par défaut)
• json : produit un JSON pour une utilisation par d’autres programmes
csvSeparator Texte Séparateur de colonnes à utiliser. Saisissez l’une des options suivantes :

, ; : | ~

Par exemple un caractère unique pour la virgule (,) , le point-virgule (;), les deux-points (:), la barre verticale (|) ou le tilde (~).

csvQuotingOption Texte Incluez ou excluez les guillemets autour de tous les champs exportés dans un fichier CSV :

  • all : incluez des guillemets autour de tous les champs.
  • none : excluez les guillemets.

Pour plus d’informations sur l’utilisation des guillemets, cliquez ici.

resolution Texte Niveau d’agrégation :

• daily (par défaut)
• quarter_hourly
• hourly
• monthly

route Texte L’identificateur du tracé ou du journal auquel le service facturé appartient.
servicePointClassCode Texte L’identifiant pour la classification/catégorie de ce point de raccordement dans le système de budgétisation, comme résidentiel, commercial, irrigation, etc.
servicePointCycle Texte Un identificateur utilisé pour désigner le nom du cycle de facturation.
site Texte Étiquette (par exemple « Campus nord », « Centre-ville ») pour filtrer dans BEACON Monitor.
unit Texte Unité utilisée pour présenter les données de débit :

• acrefeet
• ccf
• cubicfeet
• cubicmeter
• gallons (par défaut)
• liter

waterType Texte Étiquette (par exemple, « chaude », « froide », « potable », « recyclée ») pour filtrer dans BEACON Monitor.

POST EDS::Request

POST /v1/eds/range

# Utilisez ces paramètres pour soumettre une requête pour exporter# les données de débit sur une plage de dates.
#
servicePointCycle=11111
startDate=2015-08-23T22:06:09Z
endDate=2015-12-31T22:06:09Z
headerColumns=Account_ID,Meter_ID,Read
#

curl

# Utilisez cette déclaration cURL pour publier une requête # pour exporter les données de débit sur une plage de dates.
#
curl -uusername:password \
-H "Content-Type: application/x-www-form-urlencoded" \
-F servicePointCycle=11111
-F district=las \
-F startDate=2015-08-23 \
-F endDate=2015-12-31T22:06:09Z \
-F headerColumns=Account_ID,Meter_ID,Read \
https://api.beaconama.net/v1/eds/range
#

POST EDS::Response

{
    "edsUUID": "70FC1B71-F0C3-4950-885C-A635E7C4E034",
    "statusUrl": "/v1/eds/status/70FC1B71-F0C3-4950-885C-A635E7C4E034"
}

Response

Renvoie un objet EDSNew.

202 Accepté – La requête EDS a été soumise correctement et il est possible de suivre l’état sur l’emplacement statusUrl.

• l’en-tête d’emplacement renvoie vers statusUrl

POST /v1/eds/read

Soumet une requête pour récupérer les données de lecture de facturation les plus récentes pour les filtres et la tolérance indiqués.

Remarque : l’en-tête Content-Type doit être défini sur application/x-www-form-urlencoded dans la requête.

Paramètres :

csvQuotingOption
Texte

Incluez ou excluez les guillemets autour de tous les champs exportés dans un fichier CSV :

  • all : incluez des guillemets autour de tous les champs.
  • none : excluez les guillemets.

Pour plus d’informations sur l’utilisation des guillemets, cliquez ici.

syncTolerance
NombreLe nombre de minutes à remonter pour rechercher la dernière lecture. S’il n’est pas fourni, il est défini par défaut sur 15 minutes.tolerance
NombreLe nombre d’heures auxquelles revenir en arrière pour la dernière lecture. Doit être >= 24. S’ils ne sont pas indiqués, EDS renvoie la dernière lecture disponible pour chaque compteur.

Nom du paramètre Requis Type Description
buildingType Texte Étiquette (par exemple, « commerce », « restaurant », « appartements ») utilisée pour filtrer dans BEACON Monitor.
continuousFlowExpected Texte Yes/No.
date (erreur) Date Date de la requête;chaîne entre guillemets ISO 8601, par exemple « 2015-08-23T22:06:09Z ».

La valeur par défaut du code est 23:59:59 dans le fuseau horaire du compteur si l’heure n’est pas fournie.

dhsCode Texte Code du département des services de santé utilisé pour identifier les sources d’eau.
district Texte Un identifiant unique pour le district.
funding Texte Étiquette pour le filtrage sur la page Monitor (Surveillance) de BEACON.
hasEndpoint Booléen true pour limiter les résultats aux compteurs qui ont un point de terminaison, false pour les compteurs qui n’ont pas de point de terminaison, ou omettent d’inclure les deux.
headerColumns Texte Liste des noms de colonnes séparées par des virgules à inclure dans la sortie :

• Account_ID
• Billing_Read
• Billing_Read_Unit
• Encoder_Read
• Endpoint_SN
• Location_Area
• Location_Bathrooms
• Location_Building_Number
• Location_Building_Type
• Location_DHS_Code
• Location_District
• Location_Funding
• Location_ID
• Location_Irrigated_Area
• Location_Irrigation
• Location_Main_Use
• Location_Pool
• Location_Population
• Location_Site
• Location_Water_Type
• Location_Year_Built
• Meter_ID
• Portal_Email
• Portal_ID
• Read
• Read_Method
• Read_Time
• Read_Unit
• Register_Number
• Service_Point_ID
• Service_Point_Timezone
• Tamper_Code

includeReads Texte Exporte les enregistrements de tous les compteurs, compteurs avec ou compteurs sans lecture de facturation actuelle. S’il n’est pas fourni, il est défini par défaut sur all.

Saisissez l’une des valeurs suivantes :
• all (tous)
• with (avec)
• without (sans)Lectures de facturation actuelles = une lecture de facturation qui est comprise dans le paramètre de tolérance donné.Si la lecture actuelle est = à la lecture précédente, ou si la lecture actuelle est = 0, alors la lecture sera renvoyée.

limit Nombre Limitent le nombre de compteurs pour lesquels des données sont renvoyées, utilisés pour la pagination. La valeur par défaut est de 10000. Doit être comprise entre 1 et 10000.
mainUse Texte Étiquette pour le filtrage sur la page Monitor (Surveillance) de BEACON.
meterID Texte Un identifiant pour le compteur; peut être fourni plusieurs fois.
meterSize Texte Taille numérique du compteur. (5/8 = 0,625, 3/4 = 0,75, 1 1/2 = 1,5; etc.)
lastMeterID Texte Identifiant facultatif utilisé pour la pagination des résultats de compteur.
outputFormat Texte Format de sortie à utiliser :
• csv : produit des fichiers CSV simples avec des chaînes entre guillemets si nécessaire (format par défaut).
• json : produit un JSON pour une utilisation par d’autres programmes.
csvSeparator Texte Séparateur de colonnes à utiliser. Saisissez l’une des options suivantes :

, ; : | ~

Par exemple un caractère unique pour la virgule (,) , le point-virgule (;), les deux-points (:), la barre verticale (|) ou le tilde (~).

route Texte L’identificateur du tracé ou du journal auquel le service facturé appartient.
servicePointClassCode Texte L’identifiant pour la classification/catégorie de ce point de raccordement dans le système de budgétisation, comme résidentiel, commercial, irrigation, etc.
servicePointCycle Texte Un identificateur utilisé pour désigner le nom du cycle de facturation.
site Texte Étiquette (par exemple « Campus nord », « Centre-ville ») pour filtrer dans BEACON Monitor.
syncRegisters Booléen True pour synchroniser la lecture et les heures de lecture pour les éléments indicateurs des compteurs combinés selon le paramètre syncTolerance (voir ci-dessous). S’il n’est pas fourni, il est défini par défaut sur False.
waterType Texte Étiquette (par exemple, « chaude », « froide », « potable », « recyclée ») pour filtrer dans BEACON Monitor.

POST EDS::Request

POST /v1/eds/read

# Utilisez ces paramètres pour soumettre une requête pour récupérer # les données de lecture de facturation les plus récentes pour les filtres# et la tolérance indiqués.
#
meterId=abc123
meterId=xyz789
date=2015-08-23T22:06:09Z
tolerance=72
headerColumns=Account_ID,Meter_ID,Read
#

curl

# Utilisez cette déclaration cURL pour publier une requête# pour récupérer les données de lecture de facturation les plus récentes pour # les filtres et la tolérance indiqués.
#
curl -uusername:password \
-H "Content-Type: application/x-www-form-urlencoded" \
-F meterId=abc123 \
-F meterId=xyz789 \
-F date=2015-12-31T22:06:09Z \
-F tolerance=72 \
-F headerColumns=Account_ID,Meter_ID,Read \
https://api.beaconama.net/v1/eds/read
#

POST EDS::Response

{
    "edsUUID": "70FC1B71-F0C3-4950-885C-A635E7C4E034",
    "statusUrl": "/v1/eds/status/70FC1B71-F0C3-4950-885C-A635E7C4E034"
}

Response

Renvoie un objet EDSNew.

202 Accepté – La requête EDS a été soumise correctement et il est possible de suivre l’état sur l’emplacement statusUrl.

POST /v1/eds/exception_range

Soumet une requête pour récupérer un rapport des exceptions historiques

Remarque : l’en-tête Content-Type doit être défini sur application/x-www-form-urlencoded dans la requête.

Paramètres :

Nom du paramètre Requis Type Description
buildingType Texte Étiquette facultative indiquant le type de bâtiment (par exemple, « commerce », « restaurant », « appartements »)
continuousFlowExpected Texte Oui/non.
dhsCode Texte Code du Département des services de santé facultatif
district Texte

Un identifiant unique pour le district

endDate (erreur) Date Date de la requête;chaîne entre guillemets ISO 8601, par exemple "2015-08-23T22:06:09Z".

La valeur par défaut du code est 23:59:59 dans le fuseau horaire du compteur si l’heure n’est pas fournie

funding Texte Étiquette de budget facultative
hasEndpoint Booléen true pour limiter les résultats aux compteurs qui ont un point de terminaison, false pour les compteurs qui n’ont pas de point de terminaison, ou omettent d’inclure les deux
headerColumns Texte Liste des noms de colonnes séparées par des virgules à inclure dans la sortie :

  • Location_Name
  • Register_Number
  • Endpoint_SN
  • Meter_ID
  • Meter_SN (Numéro de série du compteur)
  • Service_Point_Timezone
  • Exception_Start_Date
  • Exception_End_Date
  • Exception
  • Account_ID
  • Location_ID
  • Account_Full_Name
  • Billing_Address_Line1
  • Billing_Address_Line2
  • Billing_Address_Line3
  • Billing_City
  • Billing_State
  • Billing_Zip
  • Service_Point_ID
  • Service_Point_Class_Code
  • Service_Point_Route
  • Service_Point_Cycle
  • Meter_Manufacturer
  • Meter_Model
  • Register_Resolution
  • Register_Unit_Of_Measure
  • Meter_Size
  • Meter_Size_Desc
  • Cadrans
  • Service_Point_Latitude
  • Service_Point_Longitude
  • Endpoint_Type
  • Connector_Type
  • Endpoint_Status
  • Supply_Zone_ID
  • Demand_Zone_ID
limit Nombre Limitent le nombre de compteurs pour lesquels des données sont renvoyées, utilisés pour la pagination. La valeur par défaut est de 10000. Doit être comprise entre 1 et 10 000
mainUse Texte Étiquette facultative d’utilisation principale

meterID

Texte

Un identifiant pour le compteur; peut être fourni plusieurs fois

meterSize Texte Taille numérique du compteur (5/8 = 0,625, 3/4 = 0,75, 1 1/2 = 1,5, etc.)
offset Nombre Décalage initial facultatif (basé sur 0) pour la pagination des résultats de compteur.
outputFormat Texte Format de sortie à utiliser :

  • csv : produit des fichiers CSV simples avec des chaînes entre guillemets si nécessaire (format par défaut)
  • json : produit un JSON pour une utilisation par d’autres programmes
route Texte L’identificateur du tracé ou du journal auquel le service facturé appartient
servicePointClassCode Texte L’identifiant pour la classification/catégorie de facturation de ce point de raccordement dans le système de facturation, comme résidentiel, commercial, irrigation, etc.

servicePointCycle

Texte

Un identificateur utilisé pour désigner le nom du cycle de facturation

site Texte Étiquette facultative de site (par exemple, « Campus nord », « Centre-ville »)
startDate (erreur) Date Date de la requête;chaîne entre guillemets ISO 8601, par exemple "2015-08-23T22:06:09Z".

La valeur par défaut du code est 23:59:59 dans le fuseau horaire du compteur si l’heure n’est pas fournie

waterType Texte Étiquette facultative de type d’eau (par exemple, « chaude », « froide », « potable », « recyclée »)

POST EDS::Request

POST /v1/eds/exception_range

servicePointCycle=11111
startDate=2016-02-01T00:00:00Z
endDate=2016-02-29T23:59:59Z
headerColumns=Account_ID,Meter_ID,Exception_Start_Date,Exception_End_Date,Exception

curl

curl -X POST -uusername:password \
-H "Content-Type: application/x-www-form-urlencoded" \
-d servicePointCycle=11111 \
-d district=las \
-d startDate=2016-02-01T00:00:00Z \
-d endDate=2016-02-29T23:59:59Z \
-d headerColumns=Account_ID,Meter_ID,Exception_Start_Date,Exception_End_Date,Exception \
https://api.beaconama.net/v1/eds/exception_range

POST EDS::Response

{
    "edsUUID": "70FC1B71-F0C3-4950-885C-A635E7C4E034",
    "statusUrl": "/v1/eds/status/70FC1B71-F0C3-4950-885C-A635E7C4E034"
}

Response

Renvoie un objet EDSNew.

202 Accepté – La requête EDS a été soumise correctement et il est possible de suivre l’état sur l’emplacement statusUrl.

• l’en-tête d’emplacement renvoie vers statusUrl

GET /v1/eds/status/{edsUUID}

Récupère l’état de la requête d’exportation des données de lecture de facturation pour l’EDS UUID fourni.

Paramètres :

Nom du paramètre Requis Type Description
edsUUID (erreur) UUID Un identifiant pour la requête.

GET EDS::Request

# # Utilisez cette commande pour récupérer l’état# le plus récent de l’exportation de lecture de facturation.
#GET /v1/eds/status/70FC1B71-F0C3-4950-885C-A635E7C4E034#

curl

# Utilisez cette déclaration cURL pour récupérer# l’état d’exportation de la lecture de facturation.
#curl -uusername:password https://api.beaconama.net/v1/eds/status/70FC1B71-F0C3-4950-885C-A635E7C4E034#

GET EDS status::Response::Queued

{    
    "state": "queue",
    "message": "Export operation queued for processing.",
    "queueTime": "2015-01-14T23:50:59Z"
}

GET EDS status::Response::Running

{    
    "startTime": "2015-01-15T00:00:00Z",
    "state": "run",
    "progress": {
        "percentComplete": "12.0",
        "ETA": "2015-01-15T01:02:31Z",
        "message": "performing validation"
    },
    "message": "Export operation running.",
    "queueTime": "2015-01-14T23:50:59Z"
}

GET EDS status::Response::Exception

{
    "startTime": "2015-01-15T00:00:00Z",
    "state": "exception",
    "endTime": "2015-01-15T01:02:30Z",
    "message": "Export operation had problems.",
    "queueTime": "2015-01-14T23:50:59Z"
}

GET EDS status::Response::Complete

{    
    "startTime": "2015-01-15T00:00:00Z",
    "state": "done",
    "endTime": "2015-01-15T01:02:30Z",
    "message": "Export operation succeeded.",
    "queueTime": "2015-01-14T23:50:59Z",
    "reportUrl": "/v1/content/. . ."
}

Response

Returns EDSStatus object.

Formats d’exportation CSV

Formats d’exportation CSV du débit

Cette définition de format de fichier CSV décrit la sortie de lecture de facturation de BEACON. Chaque ligne représente une lecture depuis un registre unique d’un compteur. Les identifiants, les données de lecture et l’heure de lecture sont toujours fournis. Les champs restants comme les initiales du lecteur et les codes de lecture sont inclus si les lectures ont été enregistrées à l’aide d’un système de lecture mobile Badger Meter. Les lectures obtenues à partir de points de terminaison de réseau fixe et cellulaires ne fournissent pas ces informations.

Nom de colonne Longueur maximale Format Description
Account_ID 32 Texte Identifiant du compte utilisé à des fins de facturation.
Location_ID 40 Texte Identifiant unique de l’emplacement où le service est fourni.
Service_Point_ID 40 Texte Un identifiant utilisé pour distinguer plusieurs raccordements de service au même emplacement. La combinaison de l’ID de l’emplacement et de celui du point de raccordement constitue un point unique auquel un compteur doit être relié.
Meter_ID 24 Texte Identifiant du compteur. Il est obligatoire et doit être unique.
Endpoint_SN 20 Texte Numéro de série du point de terminaison apparié au compteur spécifié.
Point_1_Read 9 Nombre La première lecture disponible sur la plage de dates demandée.
Point_1_Read_Time 22 AAAA-MM-JJhh:mm:ss Date et heure de la première lecture. (2014-09-10 10:39:41)
Point_2_Read 9 Nombre La dernière lecture disponible sur la plage de dates demandée.
Point_2_Read_Time 22 AAAA-MM-JJhh:mm:ss Date et heure de la dernière lecture. (2014-09-10 10:39:41)
Read_Unit 20 Texte L’unité de mesure pour les lectures.
Time_Zone 40 Texte Fuseau horaire du compteur.
Flow 9 Nombre Débit agrégé entre les dates de début et de fin.
Flow_Units 20 Texte L’unité de mesure pour le débit.

Formats d’exportation CSV de lecture

Cette définition de format de fichier CSV décrit la sortie de lecture de facturation de BEACON. Chaque ligne représente une lecture depuis un registre unique d’un compteur. Les identifiants, les données de lecture et l’heure de lecture sont toujours fournis. Les champs restants comme les initiales du lecteur et les codes de lecture sont inclus si les lectures ont été enregistrées à l’aide d’un système de lecture mobile Badger Meter. Les lectures obtenues à partir de points de terminaison de réseau fixe et cellulaires ne fournissent pas ces informations.

Nom de colonne Longueur maximale Format Description
Account_ID 32 Texte Identifiant du compte utilisé à des fins de facturation.
Location_ID 40 Texte Identifiant unique de l’emplacement où le service est fourni.
Service_Point_ID 40 Texte Un identifiant utilisé pour distinguer plusieurs raccordements de service au même emplacement. La combinaison de l’ID de l’emplacement et de celui du point de raccordement constitue un point unique auquel un compteur doit être relié.
Meter_ID 24 Texte Identifiant du compteur. Il est obligatoire et doit être unique.
Register_Number 1 Texte Identifie si le compteur est simple ou combiné. Pour les compteurs simples, la valeur sera vide ou nulle. Pour les compteurs combinés, un 0 ou un L identifie les registres à débit faible. Un 2 ou un H identifie les registres à débit élevé.
Endpoint_SN 20 Texte Numéro de série du point de terminaison apparié au compteur spécifié.
headerColumns Texte Liste des noms de colonnes séparées par des virgules à inclure dans la sortie :

• Account_ID
• Billing_Read
• Billing_Read_Unit
• Encoder_Read
• Endpoint_SN
• Location_Area
• Location_Bathrooms
• Location_Building_Number
• Location_Building_Type
• Location_DHS_Code
• Location_District
• Location_Funding
• Location_ID
• Location_Irrigated_Area
• Location_Irrigation
• Location_Main_Use
• Location_Pool
• Location_Population
• Location_Site
• Location_Water_Type
• Location_Year_Built
• Meter_ID
• Portal_Email
• Portal_ID
• Read
• Read_Method
• Read_Time
• Read_Unit
• Register_Number
• Service_Point_ID
• Service_Point_Timezone
• Tamper_Code

Read_Method 7 Texte Comment la lecture du compteur a été obtenue : Network, AMR, Manual ou Utility.
Read 9 Nombre La lecture sur le registre de l’encodeur disponible pendant la période demandée lorsque le fichier a été soumis à BEACON, multipliée par la résolution du registre.
Read_Unit 8 Texte L’unité de mesure pour les lectures.
Billing_Read 9 Nombre La lecture du compteur disponible pendant la période demandée lorsque le fichier a été soumis à BEACON, utilisée à des fins de facturation.
Read_Unit 9 Nombre L’unité de mesure pour les lectures.
Encoder_Read 9 Nombre La lecture sur le registre de l’encodeur disponible pendant la période demandée lorsque le fichier a été soumis à BEACON.
Read_Time 22 AAAA-MM-JJ hh:mm:ss Date et heure de la lecture.
(2014-09-10 10:39:41)
Service_Point_Timezone 64 Texte Nom du fuseau horaire dans lequel le service/compteur se situe, par exemple US/Pacific. Si aucun fuseau horaire n’a été fourni, le fuseau horaire associé à l’installation dans BEACON sera utilisé.
Tamper_Code 7 Texte Un code qui représente une condition de point de terminaison telle qu’une fuite potentielle (L), une non-utilisation (U), un débit inverse (R) ou un fil coupé (T).

Codes d’état HTTP

Code Description
202 Accepted Requête acceptée et il doit y avoir du contenu, considérez que l’opération est en cours.
400 Bad Request Requête mal formatée.
401 Unauthorized Aucun en-tête d’autorisation, ou pas autorisé.
403 Forbidden L’utilisateur ne dispose pas de la permission.
404 Not Found Renvoyé lorsqu’aucune ressource interne n’est trouvée.

Objets

Pagination

Les résultats JSON qui sont paginés sont renvoyés dans un objet wrapper de pagination, les objets réels étant dans une propriété de résultats.

propriété type description
total int Le nombre total dans la série.
from int Le premier numéro d’enregistrement de la série dans ces résultats. En commençant à 1.
to int Le dernier numéro d’enregistrement de la série dans ces résultats. En commençant à 1.
results tableau d’objets Un tableau des objets de résultats – voir l’API pour le type d’objet.

EDSNew

Objets créés au moment d’une nouvelle requête EDS.

propriété type description
edsUUID UUID UUID de la requête EDS.
statusURL URL URL pour vérifier l’état de l’exécution EDS.

EDSStatus

Appels qui renvoient l’état d’une requête EDS.

propriété type description
startTime date Date à laquelle le traitement a commencé.
endTime date Date à laquelle le traitement s’est arrêté.
queueTime date Date de chargement.
state enum État actuel d’un EDS {queue, run, exception, done}.
message string (chaîne) Message lisible par l’utilisateur décrivant l’état.
progress Progrès Progression actuelle.
reportUrl URL Lorsque le traitement est terminé – où trouver les données exportées.

Progression

propriététypedescription

Description de la tâche actuelle.

percentComplete float (flottant) Progression actuelle.
ETA date Date de fin estimée.
message string (chaîne)

Schéma des processus de l’API BEACON Export Data Services

Dernière mise à jour Ce qui a changé Ce que vous devez effectuer
22 décembre 2020 – Version 1.5.3 Ajout du paramètre includeReads à /v1/eds/read. Utilisez le nouveau paramètre si nécessaire.
30 novembre 2020 – Version 1.5.2 Ajout des paramètres syncRegisters et syncTolerance à /v1/eds/read. Utilisez les nouveaux paramètres si nécessaire.
16 octobre 2019 – version 1.5.1 Ajout du paramètre csvSeparator pour spécifier le séparateur de colonne souhaité. Si vous le souhaitez, utilisez le nouveau paramètre pour spécifier parmi le point-virgule (;), les deux-points (:), la barre verticale (|) ou le tilde (~). Si aucun séparateur n’est spécifié, une virgule (,) sera utilisée comme séparateur de colonnes.
7 octobre 2019 – version 1.5 Ajout du point de terminaison v1/eds/exception_range. Appelez le nouveau point de terminaison pour récupérer les rapports d’exceptions historiques sur une plage de dates donnée.
28 mai 2019 – version 1.4.9 Ajout de la notification concernant l’URL canadienne. Les services d’eau qui se connectent à BEACON sur beaconama.ca doivent modifier tous leurs appels de points de terminaison d’API en api.beaconama.ca.
1er février 2019 – version 1.4.9 Le paramètre Offset a été rendu obsolète et remplacé par lastMeterID pour les résultats de pagination. Utilisez le nouveau paramètre lastMeterID pour paginer les résultats selon vos besoins.
25 mai 2018 – version 1.4.8 Ajout de la prise en charge des options all et none pour POST /eds/v1/flow, POST /eds/v1/consumption et POST /eds/v1/range. Si vous le souhaitez, utilisez les nouvelles options de guillemets.
30 avril 2018 – version 1.4.7 Ajout de la prise en charge de Num_Meter headerColumn pour POST /eds/v1/consumption. Lorsqu’il est inclus, Num_Meters compte le nombre de compteurs avec un débit > 0. Si vous le souhaitez, utilisez le nouveau headerColumn.
13 novembre 2017 – version 1.4.6 La tolérance n’est plus requise pour POST /EDS/v1/Reads. S’ils ne sont pas indiqués, EDS renvoie la dernière lecture disponible pour chaque compteur. Aucune action requise.
2 novembre 2017 – version 1.4.5 La liste des résolutions prises en charge a été étendue pour inclure Quarter_Hourly (lectures à intervalles de 15 minutes). Si vous utilisez les points de terminaison ORION Cellular LTE, vous pouvez désormais exporter des lectures à intervalles d’un quart d’heure.
4 octobre 2017 – version 1.4.4 Ajout de documentation pour /v1/eds/consumption/. Suppression de la prise en charge de la sortie raw. Utilisez le point de terminaison de consommation v1 si nécessaire.
26 septembre 2016 – version 1.4.3 Augmentation du nombre de compteurs de 10 000 à 25 000 par appel d’exportation. Étendez vos appels d’exportations et vos décalages d’exportations successives en conséquence.
27 juillet 2016 – version 1.4.2 Ajout des paramètres hasEndpoint, meterSize et servicePointClassCode et extension de la liste des columnHeaders pris en charge. Utilisez les nouveaux paramètres et columnHeaders si nécessaire.
30 juin 2016 – version 1.4.1 Révision de la définition des formats d’exportation CSV de lecture pour inclure les en-têtes de colonnes. Ajout d’en-têtes de colonnes à vos exportations CSV de lectures, si nécessaire.
12 avril 2016 – version 1.4 Cette mise à jour importante a répondu à des demandes émanant des services d’eau en ajoutant la prise en charge de plusieurs nouvelles options d’exportation : débit, plage de dates, lectures sélectionnées par filtre, exportation d’en-têtes de colonnes. Révisez votre code d’API en fonction de cette mise à jour importante.
23 mars 2016 – version 1.3 Ajout de la prise en charge pour l’exportation de lecture de facturation dans Badger Meter Read Center Format C. Ajoutez votre code si cette fonction est importante pour vous.
29 février 2016 – version 1.2 Ajout des formats de sortie raw et display pour améliorer la compatibilité d’affichage avec les programmes de facturation et de feuille de calcul. Ajoutez votre code si cette fonction est importante pour vous.
19 février 2016 – version 1.1 Ajout de la prise en charge pour spécifier les en-têtes de colonnes incluses dans les exportations. Ajoutez votre code si cette fonction est importante pour vous.
12 février 2016 – version 1.0 Nouvelle URL pour accéder aux points de terminaison de notre API. Mettez à jour les URL de votre code conformément à la documentation.
Knowledge Base

User Guide
Follow via Email

Enter your email address to get new content notifications by email.

%d blogueurs aiment cette page :