API del Export Data Service v1

(Última actualización el 16 de octubre de 2019)


NOTA PARA LOS USUARIOS DE LA API DE BEACON EN CANADÁ

De acuerdo con las regulaciones canadienses sobre datos transfronterizos, sus datos de servicios públicos se trasladan o ya se trasladaron a Canadá. Como resultado, si inicia sesión en BEACON a través de beaconama.ca, deberá ajustar todas sus llamadas a la interfaz de programación de aplicaciones (application programming interface, API) para abordar las terminales en api.beaconama.ca.

Por ejemplo, cambie
https://api.beaconama.net/v1/eds/read/
a
https://api.beaconama.ca/v1/eds/read/

Este cambio afecta a todas las llamadas a la terminal de la API para las empresas de servicios públicos que inician sesión en beaconama.ca.


La API del Export Data Service v1 proporciona los siguientes métodos para admitir la funcionalidad de exportación de datos.

/v1/eds/flow

Método Descripción
POST Publique una solicitud para exportar datos de flujo agregados y lecturas en una fecha inicial y final.

/v1/eds/consumption

Método Descripción
POST Publique una solicitud para exportar el consumo total agregado.

/v1/eds/formatc

Método Descripción
POST Publique una solicitud para exportar los datos de lectura de facturación más recientes utilizando archivos de entrada de formato C.

/v1/eds/range

Método Descripción
POST Publique una solicitud para exportar datos de flujo dentro de un rango de fechas.

/v1/eds/read

Método Descripción
POST Publique una solicitud para exportar los últimos datos de lectura de facturación más recientes.

/v1/eds/exception_range

Método Descripción
POST Publique una solicitud para exportar una lista de alertas de los medidores, codificadores y terminales junto con las fechas inicial y final de las alertas.

/v1/eds/status{edsUUID}

Método Descripción
GET Recupera el estado actual del proceso de exportación, incluido un localizador de recursos uniforme (uniform resource locator, URL) para descargar los resultados de la exportación, cuando estén disponibles.

Export Data Services de BEACON

POST /v1/eds/flow

 

Envía una solicitud para recuperar los datos de flujo agregados de exportación y las lecturas en una fecha inicial y final. Consulte el Diagrama de procesos de la API del Export Data Service de BEACON.

Nota: El encabezado Content-Type debe asignarse como application/x-www-form-urlencoded en la solicitud.

Parámetros:

startDate(error)Fecha

Fecha solicitada; cadena entre comillas ISO 8601, p. ej. «2015-08-23T22:06:09Z».

El código predeterminado será 23:59:59 en la zona horaria del medidor si no se proporciona el componente de hora.

Nombre del parámetro Requerido Tipo Descripción
buildingType Texto La etiqueta (p. ej. «tienda», «restaurante», «apartamentos») se usa para filtrar en el Monitor de BEACON.
continuousFlowExpected Texto Sí/No.
dhsCode Texto El código del Departamento de Servicios de Salud se usa para identificar fuentes de agua.
district Texto Un identificador único para el distrito.
endDate (error) Fecha Fecha solicitada; cadena entre comillas ISO 8601, p. ej. «2015-08-23T22:06:09Z».

El código predeterminado será 23:59:59 en la zona horaria del medidor si no se proporciona el componente de hora.

funding Texto La etiqueta se usa para filtrar en el Monitor de BEACON.
hasEndpoint Booleano Es verdadero para limitar los resultados de los medidores que tienen una terminal, es falso para los medidores que no tienen una terminal, o se omite para incluir ambos.
headerColumns Texto Lista de nombres de columna separadas por comas para incluir en la salida:

• 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 Número Limita el número de medidores para los que se recuperan los datos; se utiliza para la paginación. El valor predeterminado es 25000. Debe estar entre 1 y 25000.
mainUse Texto La etiqueta se usa para filtrar en el Monitor de BEACON.
meterId Texto Es un identificador del medidor; se puede proporcionar varias veces.
meterSize Texto Tamaño numérico del medidor. (5/8 = .625, 3/4 = .75, 1 1/2 = 1.5, etc.)
lastMeterID Texto Identificador opcional utilizado para la paginación de los resultados del medidor.
outputFormat Texto Formato de salida a utilizar:
• csv: produce archivos CSV simples con cadenas entre comillas cuando es necesario (predeterminado).
• json: produce JSON para su uso en otros programas.
csvSeparator Texto Separador de columnas a utilizar. Ingrese alguna opción, ya sea:

, ; : | ~

p. ej. un solo carácter para coma (,) , punto y coma (;), dos puntos (:), barra (|) o virgulilla (~).

csvQuotingOption Texto Incluya o excluya las comillas alrededor de todos los campos exportados en un archivo CSV:

  • todos: comillas en todos los campos.
  • ninguno: excluir comillas.

Para obtener más información sobre el uso de comillas, haga clic aquí.

route Texto Identificador de la ruta o cartera a la que pertenece el servicio de medidor.
servicePointClassCode Texto Identificador de la clasificación/categoría de facturación de este punto de servicio en el sistema de facturación, p. ej. residencial, comercial, riego, etc.
servicePointCycle Texto Un identificador que se usa para indicar el nombre del ciclo de facturación.
site Texto La etiqueta (p. ej. «Campus Norte», «Norte de la ciudad») se usa para filtrar en el Monitor de BEACON.
unit Texto Unidad en la cual se presentarán los datos de flujo:

• acres pies
• ccf
• pies cúbicos
• metros cúbicos
• galones (predeterminado)
• litros

waterType Texto La etiqueta (p. ej. «caliente», «fría», «potable», «regenerada») se usa para filtrar en el Monitor de BEACON.

Método POST en el EDS::Solicitud

POST /v1/eds/flow

# Use estos parámetros a fin de publicar una solicitud para exportar los datos de flujo
# agregados y las lecturas para una fecha inicial y final.
#
servicePointCycle=11111
startDate=2016-02-01T00:00:00Z
endDate=2016-02-29T23:59:59Z
headerColumns=Account_ID,Meter_ID,Flow
#

curl

# Use este enunciado cURL a fin de publicar una solicitud para exportar los datos de flujo
# agregados y las lecturas para una fecha inicial y final.
#
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
#

Método POST del EDS::Respuesta

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

Respuesta

Da como respuesta el objeto EDSNew.

202 Accepted: La solicitud del EDS se envió correctamente y se puede seguir el estado en la ubicación statusUrl.

POST /v1/eds/consumption

Esto envía una solicitud para recuperar los datos de consumo agregados en una fecha inicial y final.

Nota: El encabezado Content-Type debe asignarse como application/x-www-form-urlencoded en la solicitud.

 

Parámetros:

Nombre del parámetro Requerido Tipo Descripción
endDate (error) Fecha Fecha solicitada; cadena entre comillas ISO 8601, p. ej. “2015-08-23T22:06:09Z”.
El código predeterminado será 23:59:59 en la zona horaria del medidor si no se proporciona el componente de hora.
hasEndpoint Booleano Es verdadero para limitar los resultados de los medidores que tienen una terminal, es falso para los medidores que no tienen una terminal, o se omite para incluir ambos.
headerColumns (error) Texto Lista de nombres de columna para incluir en la salida:

Day_of_Week
Flow
Flow_Time
Flow_Unit
Num_Meters

Num_Meters cuenta el número total de medidores con un flujo >0.

limit Número Limita el número de medidores para los que se recuperan los datos; se utiliza para la paginación. El valor predeterminado es 25000. Debe estar entre 1 y 25000.
buildingType Texto La etiqueta (p. ej. «tienda», «restaurante», «apartamentos») se usa para filtrar en el Monitor de BEACON.
dhsCode Texto El código del Departamento de Servicios de Salud se usa para identificar fuentes de agua.
district Texto Un identificador único para el distrito.
funding Texto La etiqueta se usa para filtrar en el Monitor de BEACON.
mainUse Texto La etiqueta se usa para filtrar en el Monitor de BEACON.
site Texto La etiqueta (p. ej. «Campus Norte», «Norte de la ciudad») se usa para filtrar en el Monitor de BEACON.
waterType Texto La etiqueta (p. ej. «caliente», «fría», «potable», «regenerada») se usa para filtrar en el Monitor de BEACON.
continuousFlowExcepted Texto Sí/No.
meterId Texto Es un identificador del medidor; se puede proporcionar varias veces.
meterSize Texto Tamaño numérico del medidor. (5/8 = .625,
3/4 = .75, 1 1/2 = 1.5, etc.)
lastMeterID Texto Identificador opcional utilizado para la paginación de los resultados del medidor.
outputFormat Texto Formato de salida a utilizar:

• csv: produce archivos CSV simples con cadenas entre comillas cuando es necesario (predeterminado).

• json: produce JSON para su uso en otros programas.

csvSeparator Texto Separador de columnas a utilizar. Ingrese alguna opción, ya sea:

, ; : | ~

p. ej. un solo carácter para coma (,) , punto y coma (;), dos puntos (:), barra (|) o virgulilla (~).

csvQuotingOption Texto Incluya o excluya las comillas alrededor de todos los campos exportados en un archivo CSV:

  • todos: comillas en todos los campos.
  • ninguno: excluir comillas.

Para obtener más información sobre el uso de comillas, haga clic aquí.

resolution Texto Nivel de agregación:

  • daily (predeterminado)
  • quarter_hourly
  • hourly
  • monthly
servicePointClassCode Texto Identificador de la clasificación/categoría de facturación de este punto de servicio en el sistema de facturación, p. ej. residencial, comercial, riego, etc.
servicePointCycle Texto Un identificador que se usa para indicar el nombre del ciclo de facturación.
route Texto Identificador de la ruta o cartera a la que pertenece el servicio de medidor.
startDate (error) Fecha Fecha solicitada; cadena entre comillas ISO 8601, p. ej. “2015-08-23T22:06:09Z”.
El código predeterminado será 23:59:59 en la zona horaria del medidor si no se proporciona el componente de hora.
tolerance Número Cuántas horas debe buscar hacia atrás para ver la última lectura. Debe ser >= 24.
unit Texto Unidad en la cual se presentarán los datos de flujo:

• acres pies
• ccf
• pies cúbicos
• metros cúbicos
• galones (predeterminado)
• litros

Método POST del EDS::Solicitud

POST /v1/eds/consumption

# Use estos parámetros a fin de publicar una solicitud para exportar el consumo
# agregado para una fecha inicial y final con una tolerancia determinada.
#
servicePointCycle=11111
startDate=2016-02-01T00:00:00Z
endDate=2016-02-29T23:59:59Z
tolerance=72
headerColumns=Flow,Flow_Time,Flow_Unit 
#

curl

# Use este enunciado cURL a fin de publicar una solicitud para exportar el consumo
# agregado para una fecha inicial y final con una tolerancia determinada.
#
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
#

Método POST del EDS::Respuesta

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

Respuesta

Da como respuesta el objeto EDSNew.

202 Accepted: La solicitud del EDS se envió correctamente y se puede seguir el estado en la ubicación statusUrl.

• el encabezado de ubicación dirige hacia statusUrl

• el encabezado de ubicación dirige hacia statusUrl

POST /v1/eds/formatc

 

Publique una solicitud para exportar los datos de lectura de facturación más recientes utilizando un archivo de entrada de formato C dentro de la tolerancia determinada. Esta terminal de la API utiliza la información del medidor y de la cuenta del archivo determinado como sus filtros. Los datos recuperados estarán en formato C, de acuerdo con el archivo original, en lugar de un formato CSV.

Nota: El encabezado Content-Type debe asignarse como application/x-www-form-urlencoded en la solicitud.

Parámetros:

Nombre del parámetro Requerido Tipo Descripción
data (error) Archivo El archivo de entrada en formato C del cual se extraerá la información del medidor y de la cuenta.
date (error) Fecha Fecha solicitada; cadena entre comillas ISO 8601, p. ej. «2015-08-23T22:06:09Z».

El código predeterminado será 23:59:59 en la zona horaria del medidor si no se proporciona el componente de hora.

tolerance (error) Número Cuántas horas debe buscar hacia atrás para ver la última lectura. Debe ser >= 24.

Método POST del EDS::Solicitud

POST /v1/eds/formatc

# Use estos parámetros a fin de publicar una solicitud para exportar
# los datos de lectura de facturación más recientes utilizando un archivo de entrada de formato C, 
# dentro de la tolerancia determinada.
#
data=$HOME/Desktop/my-format-c-data.txt
date=2015-08-23T22:06:09Z
tolerance=72
#

curl

# Use este enunciado cURL a fin de publicar una solicitud para exportar
# los datos de lectura de facturación más recientes utilizando un archivo de entrada de formato C, 
# dentro de la tolerancia determinada.
#
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
#

Método POST del EDS::Respuesta

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

Respuesta

Da como respuesta el objeto EDSNew.

202 Accepted: La solicitud del EDS se envió correctamente y se puede seguir el estado en la ubicación statusUrl.

• el encabezado de ubicación dirige hacia statusUrl

POST /v1/eds/range

Envía una solicitud para exportar los datos de flujo dentro de un rango de fechas.

Nota: El encabezado Content-Type debe asignarse como application/x-www-form-urlencoded en la solicitud.
Parámetros:

startDate(error)Fecha

Fecha solicitada; cadena entre comillas ISO 8601, p. ej. «2015-08-23T22:06:09Z».

El código predeterminado será 23:59:59 en la zona horaria del medidor si no se proporciona el componente de hora.

Nombre del parámetro Requerido Tipo Descripción
buildingType Texto La etiqueta (p. ej. «tienda», «restaurante», «apartamentos») se usa para filtrar en el Monitor de BEACON.
continuousFlowExpected Texto Sí/No.
dhsCode Texto El código del Departamento de Servicios de Salud se usa para identificar fuentes de agua.
district Texto Un identificador único para el distrito.
endDate (error) Fecha Fecha solicitada; cadena entre comillas ISO 8601, p. ej. «2015-08-23T22:06:09Z».

El código predeterminado será 23:59:59 en la zona horaria del medidor si no se proporciona el componente de hora

funding Texto La etiqueta se usa para filtrar en el Monitor de BEACON.
hasEndpoint Booleano Es verdadero para limitar los resultados de los medidores que tienen una terminal, es falso para los medidores que no tienen una terminal, o se omite para incluir ambos.
headerColumns Texto Lista de nombres de columna separadas por comas para incluir en la salida:

• 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 Número Limita el número de medidores para los que se recuperan los datos; se utiliza para la paginación. El valor predeterminado es 10000. Debe estar entre 1 y 10000.
mainUse Texto La etiqueta se usa para filtrar en el Monitor de BEACON.
meterId Texto Es un identificador del medidor; se puede proporcionar varias veces.
meterSize Texto Tamaño numérico del medidor. (5/8 = .625, 3/4 = .75, 1 1/2 = 1.5, etc.)
lastMeterID Texto Identificador opcional utilizado para la paginación de los resultados del medidor.
outputFormat Texto Formato de salida a utilizar:
• csv produce archivos CSV simples con cadenas entre comillas cuando es necesario (predeterminado)
• json: produce JSON para su uso en otros programas
csvSeparator Texto Separador de columnas a utilizar. Ingrese alguna opción, ya sea:

, ; : | ~

p. ej. un solo carácter para coma (,) , punto y coma (;), dos puntos (:), barra (|) o virgulilla (~).

csvQuotingOption Texto Incluya o excluya las comillas alrededor de todos los campos exportados en un archivo CSV:

  • todos: comillas en todos los campos.
  • ninguno: excluir comillas.

Para obtener más información sobre el uso de comillas, haga clic aquí.

resolution Texto Nivel de agregación:

• daily (predeterminado)
• quarter_hourly
• hourly
• monthly

route Texto Identificador de la ruta o cartera a la que pertenece el servicio de medidor.
servicePointClassCode Texto Identificador de la clasificación/categoría de este punto de servicio en el sistema de presupuesto, p. ej. residencial, comercial, riego, etc.
servicePointCycle Texto Un identificador que se usa para indicar el nombre del ciclo de facturación.
site Texto La etiqueta (p. ej. «Campus Norte», «Norte de la ciudad») se usa para filtrar en el Monitor de BEACON.
unit Texto Unidad en la cual se presentarán los datos de flujo:

• acres pies
• ccf
• pies cúbicos
• metros cúbicos
• galones (predeterminado)
• litros

waterType Texto La etiqueta (p. ej. «caliente», «fría», «potable», «regenerada») se usa para filtrar en el Monitor de BEACON.

Método POST del EDS::Solicitud

POST /v1/eds/range

# Use estos parámetros a fin de enviar una solicitud para exportar
# datos de flujo dentro de un rango de fechas.
#
servicePointCycle=11111
startDate=2015-08-23T22:06:09Z
endDate=2015-12-31T22:06:09Z
headerColumns=Account_ID,Meter_ID,Read
#

curl

# Use este enunciado cURL a fin de publicar una solicitud para exportar
# datos de flujo dentro de un rango de fechas.
#
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
#

Método POST del EDS::Respuesta

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

Respuesta

Da como respuesta el objeto EDSNew.

202 Accepted: La solicitud del EDS se envió correctamente y se puede seguir el estado en la ubicación statusUrl.

• el encabezado de ubicación dirige hacia statusUrl

POST /v1/eds/read

Envía una solicitud a fin de recuperar los datos de lectura de facturación más recientes para los filtros y la tolerancia proporcionados.

Nota: El encabezado Content-Type debe asignarse como application/x-www-form-urlencoded en la solicitud.

Parámetros:

csvQuotingOption
Texto

Incluya o excluya las comillas alrededor de todos los campos exportados en un archivo CSV:

  • todos: comillas en todos los campos.
  • ninguno: excluir comillas.

Para obtener más información sobre el uso de comillas, haga clic aquí.

Nombre del parámetro Requerido Tipo Descripción
buildingType Texto La etiqueta (p. ej. «tienda», «restaurante», «apartamentos») se usa para filtrar en el Monitor de BEACON.
continuousFlowExpected Texto Sí/No.
date (error) Fecha Fecha solicitada; cadena entre comillas ISO 8601, p. ej. «2015-08-23T22:06:09Z».

El código predeterminado será 23:59:59 en la zona horaria del medidor si no se proporciona el componente de hora.

dhsCode Texto El código del Departamento de Servicios de Salud se usa para identificar fuentes de agua.
district Texto Un identificador único para el distrito.
funding Texto La etiqueta se usa para filtrar en el Monitor de BEACON.
hasEndpoint Booleano Es verdadero para limitar los resultados de los medidores que tienen una terminal, es falso para los medidores que no tienen una terminal, o se omite para incluir ambos.
headerColumns Texto Lista de nombres de columna separadas por comas para incluir en la salida:

• 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

limit Número Limita el número de medidores para los que se recuperan los datos; se utiliza para la paginación. El valor predeterminado es 10000. Debe estar entre 1 y 10000.
mainUse Texto La etiqueta se usa para filtrar en el Monitor de BEACON.
meterId Texto Es un identificador del medidor; se puede proporcionar varias veces.
meterSize Texto Tamaño numérico del medidor. (5/8 = .625, 3/4 = .75, 1 1/2 = 1.5, etc.)
lastMeterID Texto Identificador opcional utilizado para la paginación de los resultados del medidor.
outputFormat Texto Formato de salida a utilizar:
• csv: produce archivos CSV simples con cadenas entre comillas cuando es necesario (predeterminado).
• json: produce JSON para su uso en otros programas.
csvSeparator Texto Separador de columnas a utilizar. Ingrese alguna opción, ya sea:

, ; : | ~

p. ej. un solo carácter para coma (,) , punto y coma (;), dos puntos (:), barra (|) o virgulilla (~).

route Texto Identificador de la ruta o cartera a la que pertenece el servicio de medidor.
servicePointClassCode Texto Identificador de la clasificación/categoría de este punto de servicio en el sistema de presupuesto, p. ej. residencial, comercial, riego, etc.
servicePointCycle Texto Un identificador que se usa para indicar el nombre del ciclo de facturación.
site Texto La etiqueta (p. ej. «Campus Norte», «Norte de la ciudad») se usa para filtrar en el Monitor de BEACON.
tolerance Número Cuántas horas debe buscar hacia atrás para ver la última lectura. Debe ser >= 24. Si no se proporciona, el EDS da como respuesta la última lectura disponible para cada medidor.
waterType Texto La etiqueta (p. ej. «caliente», «fría», «potable», «regenerada») se usa para filtrar en el Monitor de BEACON.

Método POST del EDS::Solicitud

POST /v1/eds/read

# Use estos parámetros a fin de enviar una solicitud para recuperar
# los datos de lectura de facturación más recientes para los filtros
# y la tolerancia proporcionados.
#
meterId=abc123
meterId=xyz789
date=2015-08-23T22:06:09Z
tolerance=72
headerColumns=Account_ID,Meter_ID,Read
#

curl

# Use este enunciado cURL a fin de publicar una solicitud
# para recuperar los datos de lectura de facturación más recientes para los
# filtros y la tolerancia proporcionados.
#
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
#

Método POST del EDS::Respuesta

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

Respuesta

Da como respuesta el objeto EDSNew.

202 Accepted: La solicitud del EDS se envió correctamente y se puede seguir el estado en la ubicación statusUrl.

POST /v1/eds/exception_range

Envía una solicitud para recuperar un informe de excepciones históricas.

Nota: El encabezado Content-Type debe asignarse como application/x-www-form-urlencoded en la solicitud.

Parámetros:

Nombre del parámetro Requerido Tipo Descripción
buildingType Texto Etiqueta del tipo de edificio (p. ej. «tienda», «restaurante», «apartamentos») opcional
continuousFlowExpected Texto Sí/No
dhsCode Texto Código del Departamento de Servicios de Salud opcional
district Texto

Un identificador único para el distrito

endDate (error) Fecha Fecha solicitada; cadena entre comillas ISO 8601, p. ej. «2015-08-23T22:06:09Z«.
El código predeterminado será 23:59:59 en la zona horaria del medidor si no se proporciona el componente de hora
funding Texto Etiqueta de financiamiento opcional
hasEndpoint Booleano Es verdadero para limitar los resultados de los medidores que tienen una terminal, es falso para los medidores que no tienen una terminal, o se omite para incluir ambos
headerColumns Texto Lista de nombres de columna separados por comas para incluir en la salida:

  • Location_Name
  • Register_Number
  • Endpoint_SN
  • Meter_ID
  • Meter_SN
  • 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
  • Dials
  • Service_Point_Latitude
  • Service_Point_Longitude
  • Endpoint_Type
  • Connector_Type
  • Endpoint_Status
  • Supply_Zone_ID
  • Demand_Zone_ID
limit Número Limita el número de medidores para los que se recuperan los datos; se utiliza para la paginación. El valor predeterminado es 10000. Debe estar entre 1 y 10000.
mainUse Texto Etiqueta de uso principal opcional

meterId

Texto

Es un identificador del medidor; se puede proporcionar varias veces

meterSize Texto Tamaño numérico del medidor (5/8 = .625, 3/4 = .75, 1 1/2 = 1.5, etc.)
offset Número Compensación de inicio opcional (basada en 0) para la paginación de los resultados de medidores.
outputFormat Texto Formato de salida a utilizar:

  • csv: produce archivos CSV simples con cadenas entre comillas cuando es necesario (predeterminado)
  • json: produce JSON para su uso en otros programas
route Texto Identificador de la ruta o cartera a la que pertenece el servicio de medidor
servicePointClassCode Texto Identificador de la clasificación/categoría de facturación de este punto de servicio en el sistema de facturación, p. ej. residencial, comercial, riego, etc.

servicePointCycle

Texto

Un identificador que se usa para indicar el nombre del ciclo de facturación

site Texto Etiqueta de sitio opcional (p. ej. «Campus Norte», «Norte de la ciudad»)
startDate (error) Fecha Fecha solicitada; cadena entre comillas ISO 8601, p. ej. «2015-08-23T22:06:09Z«.
El código predeterminado será 23:59:59 en la zona horaria del medidor si no se proporciona el componente de hora
waterType Texto Etiqueta del tipo de agua opcional (p. ej. «caliente», «fría», «potable», «regenerada»)

Método POST del EDS::Solicitud

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

Método POST del EDS::Respuesta

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

Respuesta

Da como respuesta el objeto EDSNew.

202 Accepted: La solicitud del EDS se envió correctamente y se puede seguir el estado en la ubicación statusUrl.

• el encabezado de ubicación dirige hacia statusUrl

GET /v1/eds/status/{edsUUID}

Recupera el estado de la solicitud de datos de exportación de lectura de facturación para el identificador único universal (Universally Unique Identifier, UUID) del EDS proporcionado.

Parámetros:

Nombre del parámetro Requerido Tipo Descripción
edsUUID (error) UUID Un identificador de la solicitud.

Método GET del EDS::Solicitud

# # Use este comando a fin de recuperar
# el estado de exportación de lectura de facturación más reciente.
#
GET /v1/eds/status/70FC1B71-F0C3-4950-885C-A635E7C4E034
#

curl

# Use este enunciado cURL a fin de recuperar
# el estado de exportación de lectura de facturación.
#
curl -uusername:password https://api.beaconama.net/v1/eds/status/70FC1B71-F0C3-4950-885C-A635E7C4E034
#

Método GET del EDS estado::Respuesta::En cola

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

Método GET del EDS estado::Respuesta::Ejecutando

{    
    "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"
}

Método GET del EDS estado::Respuesta::Excepción

{
    "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"
}

Método GET del EDS estado::Respuesta::Completado

{    
    "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/. . ."
}

Respuesta

Da como respuesta el objeto EDSStatus.

Formatos de exportación en CSV

Formatos de exportación en CSV de flujo

Esta definición de formato de archivo CSV describe la salida de lectura de facturación de BEACON. Cada fila representa una lectura de un solo registro de un medidor. Siempre se proporcionan los identificadores, datos leídos y hora de lectura. Los campos restantes, como las iniciales del lector y los códigos de lectura, se incluyen si las lecturas se registraron utilizando un sistema de lectura móvil de Badger Meter. Las lecturas obtenidas de la red fija y terminales celulares no proporcionan esta información.

Nombre de columna Longitud máxima Formato Descripción
Account_ID 32 Texto Identificador de la cuenta utilizado para fines de facturación.
Location_ID 40 Texto Identificador único de la ubicación donde se brinda el servicio.
Service_Point_ID 40 Texto Un identificador que se usa para distinguir entre múltiples conexiones de servicio en la misma ubicación. La combinación de ID de ubicación e ID de punto de servicio representa un único punto al que se debe conectar un medidor.
Meter_ID 24 Texto Identificador del medidor. Debe ser único y es obligatorio.
Endpoint_SN 20 Texto Número de serie de la terminal vinculada con el medidor especificado.
Point_1_Read 9 Número La primera lectura disponible dentro del rango de fechas solicitado.
Point_1_Read_Time 22 AAAA-MM-DD
hh:mm:ss
Fecha y hora de la primera lectura. (2014-09-10 10:39:41)
Point_2_Read 9 Número La última lectura disponible dentro del rango de fechas solicitado.
Point_2_Read_Time 22 AAAA-MM-DD
hh:mm:ss
Fecha y hora de la última lectura. (2014-09-10 10:39:41)
Read_Unit 20 Texto La unidad de medida de las lecturas.
Time_Zone 40 Texto Zona horaria del medidor.
Flow 9 Número Flujo agregado entre las fechas de inicial y final proporcionadas.
Flow_Units 20 Texto La unidad de medida del flujo.

Formatos de exportación en CSV de lectura

Esta definición de formato de archivo CSV describe la salida de lectura de facturación de BEACON. Cada fila representa una lectura de un solo registro de un medidor. Siempre se proporcionan los identificadores, datos leídos y hora de lectura. Los campos restantes, como las iniciales del lector y los códigos de lectura, se incluyen si las lecturas se registraron utilizando el sistema de lectura móvil de Badger Meter. Las lecturas obtenidas de la red fija y terminales celulares no proporcionan esta información.

Nombre de columna Longitud máxima Formato Descripción
Account_ID 32 Texto Identificador de la cuenta utilizado para fines de facturación.
Location_ID 40 Texto Identificador único de la ubicación donde se brinda el servicio.
Service_Point_ID 40 Texto Un identificador que se usa para distinguir entre múltiples conexiones de servicio en la misma ubicación. La combinación de ID de ubicación e ID de punto de servicio representa un único punto al que se debe conectar un medidor.
Meter_ID 24 Texto Identificador del medidor. Debe ser único y es obligatorio.
Register_Number 1 Texto Identifica si un medidor es un medidor simple o compuesto. Para medidores individuales, el valor estará en blanco o 0. Para los compuestos, un 0 o una L identifica los registros de flujo bajo (low-flow). Un 2 o una H identifica los registros de flujo alto (high-flow).
Endpoint_SN 20 Texto Número de serie de la terminal vinculada con el medidor especificado.
headerColumns Texto Lista de nombres de columna separadas por comas para incluir en la salida:

• 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 Texto Cómo se obtuvo la lectura del medidor: red, lectura de medidor automatizada (Automatic Meter Reading, AMR), manual o empresa de servicios público.
Read 9 Número La lectura en el registro del codificador disponible dentro del periodo solicitado cuando el archivo se envió a BEACON multiplicado por la resolución del registro.
Read_Unit 8 Texto La unidad de medida de las lecturas.
Billing_Read 9 Número La lectura del medidor disponible dentro del periodo solicitado cuando el archivo se envió a BEACON para fines de facturación.
Read_Unit 9 Número La unidad de medida de las lecturas.
Encoder_Read 9 Número La lectura en el registro del codificador disponible dentro del periodo solicitado cuando el archivo se envió a BEACON.
Read_Time 22 AAAA-MM-DD
hh:mm:ss
Fecha y hora de la lectura.
(2014-09-10 10:39:41)
Service_Point_Timezone 64 Texto Nombre de la zona horaria donde se encuentra el servicio o medidor, p. ej. Estados Unidos/Pacífico. Si no se proporcionó una zona horaria, se utilizará la zona horaria asociada con la instalación en BEACON.
Tamper_Code 7 Texto Un código que representa una condición de la terminal, como una fuga potencial (L), sin uso (U), flujo inverso (R) o cable cortado (T).

Códigos de estado de HTTP

Código Descripción
202 Accepted Solicitud aceptada y debería incluir algo de contenido, asuma que la operación está en progreso.
400 Bad Request Solicitud con formato incorrecto.
401 Unauthorized No hay encabezado de autorización o no autorizado.
403 Forbidden El usuario no tiene permiso.
404 Not Found Respuesta obtenida cuando no se encuentra un recurso interno.

Objetos

Paginación

Los resultados de la paginación se muestran en un objeto contenedor de paginación, con los objetos reales bajo una propiedad de resultados.

propiedad tipo descripción
total int El número total en el conjunto.
from int El primer número de registro del conjunto en estos resultados. Iniciando en 1.
to int El último número de registro del conjunto en estos resultados. Iniciando en 1.
results matriz de objetos Una matriz de los objetos de resultado. Consulte la API para conocer el tipo de objeto.

EDSNew

Objetos creados en el momento de una nueva solicitud del EDS.

propiedad tipo descripción
edsUUID UUID UUID de solicitud del EDS.
statusURL URL URL para comprobar el estado de ejecución del EDS.

EDSStatus

Llamadas que dan como respuesta el estado de una solicitud del EDS.

propiedad tipo descripción
startTime fecha Fecha en que comenzó el procesamiento.
endTime fecha Fecha en que terminó el procesamiento.
queueTime fecha Fecha de la carga.
state enum Estado actual de un archivo del EDS {queue, run, exception, done}.
message cadena Mensaje en formato legible humano que describe el estado.
progress Progreso Progreso actual.
reportUrl URL Al finalizar el procesamiento: dónde encontrar los datos exportados.

Progreso

propiedadtipodescripción

Descripción del trabajo actual.

percentComplete float Progreso actual.
ETA fecha Fecha estimada de finalización.
message cadena

Diagrama de procesos de la API de Export Data Services de BEACON

Última actualización ¿Qué cambió? Lo que debe hacer
16 de octubre de 2019: Versión 1.5.1 Se añadió el parámetro csvSeparator para especificar el separador de columnas deseado. Si lo desea, use el nuevo parámetro para especificar una de las opciones, ya sea punto y coma (;), dos puntos (:), barra (|) o virgulilla (~). Si no se especifica ninguno, se utilizará una coma (,) como separador de columnas.
7 de octubre de 2019: Versión 1.5 Se añadió la terminal v1/eds/exception_range. Llame a la nueva terminal para recuperar informes de excepciones históricas durante un rango de fechas determinado.
28 de mayo de 2019: Versión 1.4.9 Se agregó la notificación del URL canadiense. Las empresas de servicios públicos que inician sesión en BEACON a través de beaconama.ca deberán cambiar todas las llamadas de terminal de la API a api.beaconama.ca.
1 de febrero de 2019: Versión 1.4.9 Se descontinuó el parámetro Offset y se reemplazó con lastMeterID para la paginación de los resultados. Use el nuevo parámetro lastMeterID para paginar los resultados según sea necesario.
25 de mayo de 2018: Versión 1.4.8 Se añadió la compatibilidad con las opciones de comillas todos y ninguno para POST /eds/v1/flow, POST /eds/v1/consumption y POST /eds/v1/range. Si lo desea, use las nuevas opciones de comillas.
30 de abril de 2018: Versión 1.4.7 Se añadió la compatibilidad con el encabezado de columna Num_Meter para POST /eds/v1/consumption. Cuando se incluye, Num_Meters cuenta la cantidad de medidores con un flujo >0. Si lo desea, use el nuevo encabezado de columna.
13 de noviembre de 2017: Versión 1.4.6 La tolerancia ya no es necesaria para POST /EDS/v1/Reads. Si no se proporciona, el EDS da como respuesta la última lectura disponible para cada medidor. No se requiere ninguna acción.
2 de noviembre de 2017: Versión 1.4.5 Se amplió la lista de resoluciones admitidas para incluir Quarter_Hourly (lecturas de intervalo de 15 minutos). Si usa terminales ORION Cellular LTE, ahora puede exportar lecturas de intervalos de un cuarto de hora.
4 de octubre de 2017: Versión 1.4.4 Se añadió la documentación para /v1/eds/consumption/. Se eliminó la compatibilidad con la salida sin formato. Use la terminal de consumo v1 según sea necesario.
26 de septiembre de 2016: Versión 1.4.3 Se amplió el número de medidores de 10,000 a 25,000 por llamada de exportación. Amplíe sus llamadas de exportación y las compensaciones de exportación sucesivas en consecuencia.
27 de julio de 2016: Versión 1.4.2 Se añadieron los parámetros hasEndpoint, meterSize y servicePointClassCode, y se amplió la lista de columnHeaders admitidos. Use los nuevos parámetros y columnHeaders según sea necesario.
30 de junio de 2016: Versión 1.4.1 Se revisó la definición del formato de exportación de lectura CSV para incluir los encabezados de columna. Agregue los encabezados de columna a sus exportaciones CSV de lectura según sea necesario.
12 de abril de 2016: Versión 1.4 Esta extensa actualización abordó las solicitudes de las empresas de servicios públicos al añadir la compatibilidad con varias opciones de exportación nuevas: flujo, rango de fechas, lecturas seleccionadas por filtro, exportación de encabezados de columna. Revise su código de API con base en esta extensa actualización.
23 de marzo de 2016: Versión 1.3 Se añadió la compatibilidad con la exportación de lectura de facturación en formato C del Badger Meter Read Center. Agregue su código si esta función es importante para usted.
29 de febrero de 2016: Versión 1.2 Se añadieron los formatos de salida sin formato y de visualización para mejorar la compatibilidad de visualización con los programas de facturación y hojas de cálculo. Agregue su código si esta función es importante para usted.
19 de febrero de 2016: Versión 1.1 Se añadió la compatibilidad para especificar los encabezados de columna incluidos en las exportaciones. Agregue su código si esta función es importante para usted.
12 de febrero de 2016: Versión 1.0 Nuevo URL para acceder a nuestras terminales de API. Actualice los URL en su código de acuerdo con la documentación.
Knowledge Base

User Guide
Follow via Email

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

A %d blogueros les gusta esto: