How to integrate with the Gisual Power Outage Intelligence Search API

This article explains how to use Gisual’s Intelligence API to search for power status at a single location. 

Usage

When you request power status from the Intelligence Search API, Gisual begins a validation process for power status at the requested location. This is an ongoing process during which you can poll for updates by submitting a request for the same location.

If a power outage is found at that location, the details of the outage, including the utility and estimated time of restoration (ETR). 

Once power has been restored and thus confirmed ON, the search is complete and you should stop polling for that location.

Power Status

Gisual will return the power status in the response data. The possible values for power status are listed in the table below:

Status	Description
validating power	Gisual is performing initial validation to confirm power status at the requested location.
power on	Power is ON at the requested location and no outage was found.
power on - outage resolved	Power is ON at the requested location and the outage has been resolved.
power off	Power is OFF at the requested location.

NOTE: You should stop polling after the status changes to "power on" or "power on - outage resolved". The API may respond with HTTP 412 errors if you continue to poll for a location after this.

Examples

Searching a location that is not affected by a power outage

This example shows the expected response for a location with power on. This customer provides the latitude and longitude of the location, as well as asset and alarm data, though those are not required.

First, the customer sends a POST request with the following JSON body:

{
  "longitude": 41.23456,
  "latitude": -75.67890,
  "asset_name": "my node",
  "asset_status": "down",
  "alarm_type": "node down",
  "alarm_subtype": "inverter failure"
}

which results in this JSON response:

{
  "asset_name": "my node",
  "power_status": "validating power"
}

The response contains the power status in the "power_status" field as well as other fields related to the outage. As is the case here, the first response may have a status of "validating power", as Gisual is performing its initial validation.

The customer can then submit the same request data to the /v10/intel URL to poll for updates. After continuing to poll, the API eventually returns that power is on:

{
  "asset_name": "my node",
  "power_status": "power on"
}

At this point Gisual has determined that there is no power outage.

Searching a location with a power outage

This example shows the expected response for a location with a power outage. Instead of coordinates, we provide the address of the location.

First, the customer sends a POST request with the following JSON body:

{
  "thoroughfare": "2600 Benjamin Franklin Pkwy",
  "locality": "Philadelphia",
  "administrative_area": "PA",
  "postal_code": "19130",
  "country": "US"
}

which results in the this JSON response:

{
  "asset_name": null,
  "power_status": "validating power"
}

As we saw in the previous example, Gisual is performing initial validation. Also note that since there was no any asset information provided, "asset_name" is null. This is normal.

The customer can then submit the same request data to the /v10/intel URL to poll for updates. Here is the response:

{
  "asset_name": null,
  "crew_status": "unknown",
  "etr": "2022-01-25T19:00:00+00:00",
  "incident_name": "GIS-S-ABC89",
  "incident_url": "https://api.gisual.com/map/12345678-abcd-0123-4567-0123456789abc/incident",
  "location": {
    "coordinates": [
      -75.03587,
      40.10871
    ],
    "type": "Point"
  },
  "num_affected": 199,
  "power_status": "power off",
  "root_cause": "unknown",
  "utility": "PECO"
}

In this response the power_status field reports that power is off. More details about the outage are available in the other fields, including the affected utility and ETR. Additionally you can use the URL from "incident_url" to link directly to the Gisual map for that incident.

Continuing to poll eventually results in a response indicating that power has been restored:

{
  "asset_name": null,
  "power_status": "power on - outage resolved"
}

At this point the outage is resolved and you can stop polling for updates.

How to use the Gisual API

Here is the life cycle for polling Gisual.  

1. Query Gisual using a physical address or a latitude / longitude pair.

2. Gisual’s initial response will be "validating power." This signifies that Gisual is in the process of confirming the power status at the requested location.

3. Continue to query every 5 minutes until a "power out" or "power on" response.

   1. Note: The determination of a power outage can be made in less than 3 minutes, even down to milliseconds in some cases. It's important to understand that assessing power status is a dynamic situation, which is why we emphasize the "on average" aspect. In certain instances, we can detect a power outage almost instantly, while in others, this process might take up to 10 minutes. We determine power is on at the 15-minute mark.

4. If the response is "power off," perform additional queries at 15-minute intervals until a response of "power on - outage resolved" is received.

   1. Once a "power on - outage resolved" response is obtained, proceed to query 1-2 more times within a 15-minute interval.  If the same status is returned again, then stop polling.

5. If the response is "power on", proceed to query 1-2 more times within a 15-minute interval.  If the same status is returned again, then stop polling.