# Introduction

<p class="callout info">
The WebAPI documentation may be found at <a href="https://egauge.net/support/webapi">egauge.net/support/webapi</a>.
</p>

<p class="callout warning">
  eGauge Systems periodically releases new firmware versions with bug fixes, enhancements,
  and new features to the WebAPI. It is recommended to use the latest eGauge firmware version.
  <a href="https://kb.egauge.net/books/egauge-meter-ui/page/checking-and-upgrading-firmware">
    <b>Click here</b></a> for information about checking and upgrading eGauge meter firmware.
</p>

<p class="callout warning">
  Be sure to select the appropriate firmware version in the WebAPI documentation for your meter
  in the upper left-hand corner of the documentation system.
  By default, the WebAPI documentation defaults to information about the latest stable
  firmware release.
</p>
The eGauge WebAPI is a JSON-based API framework that allows for automated meter configuration,
recorded data retrieval, status information, and more.

eGauge Systems provides a Python library to assist with authentication and other interactions with the eGauge
meter WebAPI and can be obtained from [Bitbucket](https://bitbucket.org/egauge/python/src/master/egauge/)
or [PyPi](https://pypi.org/project/egauge-python/) (pip).

#### Getting Started With Python

To make it easy to get started, eGauge provides an open source Python package. It can be installed with the command:

`pip install egauge-python`

With this package installed, accessing an eGauge meter becomes very simple.
For example, to fetch the hostname of the meter, you could use:

```python
from egauge import webapi

URI = "https://DEV.egaug.es" # replace DEV with meter name
USR = "USER" # replace USER with user name
PWD = "PASS" # replace PASS with password

dev = webapi.device.Device(URI, webapi.JWTAuth(USR,PWD))

print("hostname is " + dev.get("/config/net/hostname")["result"])
```

The package also contains various convenience classes to read meter data, capture waveform samples,
convert between physical units, and so on.

The official GIT repository for this package is at
[https://bitbucket.org/egauge/python/](https://bitbucket.org/egauge/python/).
Various code examples can be found in the
[examples directory](https://bitbucket.org/egauge/python/src/master/examples/).

#### Getting started without the eGauge Python library

Check out the support library page on
[WebAPI Authentication](https://kb.egauge.net/books/egauge-meter-communication/page/authentication)
for examples on authentication.

#### Common WebAPI service descriptions

See the [WebAPI documentation](https://webapi.redoc.ly) for full details and all service
endpoints available. The endpoints below are only several commonly accessed endpoints that retrieve
data and configuration.

##### [`/auth`](https://webapi.redoc.ly/stable/tag/auth)

Service used to obtain or invalidate a JSON web token used for authenticating with the WebAPI. 

##### [`/config`](https://webapi.redoc.ly/stable/tag/config)

The `/config` service allows you to read and write configuration to the meter.

##### [`/register`](https://webapi.redoc.ly/stable/tag/register)

The `/register` service provides instantanoues and historical _register_ data that is recorded
on the meter.

##### [`/local`](https://webapi.redoc.ly/stable/tag/local)

The `/local` service provides instantaneous information derived from configured channel inputs,
including RMS value, mean value, frequency value and instantanoues power and energy values if
power registers are configured.

For historical or newly generated register data, use the `/register` service.

#### Other WebAPI service descriptions

Below are the additional service endpoints not listed above. See the
[WebAPI documentation](https://webapi.redoc.ly) for full details and all service
endpoints available.

##### [`/capture`](https://webapi.redoc.ly/stable/tag/capture)

The `/capture` service is used for obtaining raw waveform data from the inputs. To obtain normal
RMS, mean or frequency from the sensors directly, use the `/local` service. For obtaining stored or
newly generated _register_ data, use the `/register` service.

##### [`/cmd`](https://webapi.redoc.ly/stable/tag/cmd)

Service used to send commands to the meter such as reboot or firmware upgrade.

##### [`/ctid`](https://webapi.redoc.ly/stable/tag/ctid)

Service used to read or configure CTid sensors from a meter or flash the LED on the sensor (EG4xxx only).

##### [`/ctrl`](https://webapi.redoc.ly/stable/tag/ctrl)

Service used for controlling supported remote devices, such as the PRM3 relay module.

##### [`/log`](https://webapi.redoc.ly/stable/tag/log)

Service used to access syslog or kernel logs. Syslog must be enabled through the `/config` service
endpoint first.

##### [`/lua`](https://webapi.redoc.ly/stable/tag/lua)

Service used for managing Lua scripts on the meter.

##### [`/providers`](https://webapi.redoc.ly/stable/tag/providers)

Service used for obtaining information about third-party providers that support meter services
such as push data sharing, push alerts, and tariffs.

##### [`/store`](https://webapi.redoc.ly/stable/tag/store)

Service used for storing and retrieving preferences and other settings typically used in
the user's web browser interface.

##### [`/remote`](https://webapi.redoc.ly/stable/tag/remote)

Service used for configuring remote devices on the meter.

##### [`/sys`](https://webapi.redoc.ly/stable/tag/sys)

Service used to obtain system information such as firmware version, uptime, serial number,
meter model, and more.