Power Outage Intelligence - Search with Webhook

Overview

With this endpoint, you can request outage Intelligence for any site locations that you provide. You can provide either latitude/longitude or address for each site. We will return any power outages we see affecting your sites.

For detailed information on how to integrate this API endpoint into your workflow, see this article.

Technical Details

This is an HTTP POST endpoint.

All requests must set the following headers:

Header Name	Header Value
Content-Type	application/json
Authorization	Bearer <your API token>

Request URL

https://api.gisual.com/v10/intel/wh

Request Body

This is the full form of the request body.

{
  "locations": [
    { 
      "longitude": -75.163674,
      "latitude" : 39.952398,
      "search_id": "ticket-24601",
      "asset_type": "cpe"
    },
    {
      "thoroughfare": "41 Ford Street",
      "locality": "San Francisco",
      "administrative_area": "CA",
      "postal_code": "94114",
      "country": "US",
      "search_id": "ticket-24602",
      "asset_type": "node"
    },
    {
      "asset_name": "Node PHL013.56",
      "asset_type": "node",
      "asset_status": "down"
    },
    ...
  ],
  "callback_url": "https://example.com/callback"
}

Our API sends responses to the callback URL provided in the request, and an HTTP 202 is returned to the caller sending this request.

The callback URL must accept a POST request with the response body format described below, as well as a POST request with an empty JSON object {}, which should not be processed, for our API to test connectivity.

If the callback URL does not respond to the test POST request or responds with an error, a 400 error is returned.

Field Details

Field name	Purpose	Type	Allowed Value(s)	Required	Default
longitude	The longitude.	Number	-180 to 180	Yes (if using lat/long)
latitude	The latitude.	Number	-90 to 90	Yes (if using lat/long)
thoroughfare	The street address	String	Any valid street address	Yes (if using address)
dependent_thoroughfare	The cross-street	String	Any	No	null
premise	The apartment or suite number, etc	String	Any	No	null
sub_premise	Any additional street address information	String	Any	No	null
dependent_locality	The neighborhood	String	Any	No	null
locality	The city, town, etc.	String	Any valid city, town, etc.	Yes (if using address)
administrative_area	The state, province, etc.	String	Any valid state/province	Yes (if using address)
postal_code	The ZIP/postal code	String	Any valid ZIP/postal code	Yes (if using address)
country	The country	String	Any valid 2-letter country code	Yes (if using address)
callback_url	A webhook URL to send responses and updates to	String	A valid URL	Yes (unless you have provided it in your account settings)	null
asset_name	The name of the asset that is alarming.	String	Any string	Yes (if using asset name instead of location)	null
asset_type	The type of asset that is alarming	String	Any valid asset type, which may be customized to your account	No	null
asset_status	Node status	String	"up" or "down"	No	null
alarm_type	Node alarm type	String	Any string	No	null
alarm_subtype	Node alarm subtype	String	Any string	No	null
search_id	User-defined search identifier	String	Any string	No	null

Response Body

The HTTP response code is 202. This is the full form of the response body.

{
    "invalid_locations": ["Node PHL013.56"],
    "online_locations": ["Node PHL013.57"],
}

Field Details

Field name	Description	Type	Default
invalid_locations	The names of assets provided in the request that could not be found.	Array[String]	[]
online_locations	The names of assets provided in the request whose asset_status was "up".	Array[String]	[]

 

Webhook Notification Body

This is the full form of the HTTP notification that is sent to the callback URL.

If an asset name or search_id is provided with the request, it will be provided in the response.

{
  "asset_name": null,
  "incident_name": null,
  "incident_url": null,
  "power_status": "power on",
  "search_id": "alarm-24601"
}
...
{
  "asset_name": null,
  "incident_name": "GIS-DSL3M",
  "incident_url": "https://app.gisual.com/map/83aa8cab-a297-4128-9e20-65ca477e1230/incident",
  "etr": "2020-08-20T17:35:12-04:00",
  "location": {"coordinates": [-122.4339457, 37.7618972], "type": "Point"},
  "num_affected": 5,
  "utility": "PSE&G",
  "power_status": "power off",
  "crew_status": "unknown",
  "root_cause": "down tree",
  "search_id": "alarm-24602"
}
...
{
  "asset_name": "Node PHL013.56",
  "incident_name": "GIS-ARB8W",
  "incident_url": "https://app.gisual.com/map/83aa8cab-a297-4128-9e20-65ca477e1230/incident",
  "power_status": "power off",
  "etr": "2020-08-20T21:55:00-04:00",
  "location": {"coordinates": [-75.164299, 39.907011], "type": "Point"},
  "num_affected": 43,
  "utility": "PECO",
  "crew_status": "dispatched",
  "root_cause": "unknown",
  "search_id": null
}

Field Details

Field name	Description	Type	Default
asset_name	The name of the asset provided with the search request, if any.	String	null
incident_name	The name of the incident Gisual's system created to track the outage	String	null
incident_url	The URL to open the incident in Gisual's Web Tool	String	null
power_status	The power status of the location "validating power" "power on" "power on - outage resolved" "power off"	String
etr	The outage's estimated time of resolution, given in the time zone local to the utility.	String
location	The outage's location as a GeoJSON object.	Object
num_affected	The number of electric customers affected by the outage.	Number
utility	The name of the utility the outage belongs to.	String
crew_status	The current status of the utility crew.	String
root_cause	The root cause of the utility outage.	String
search_id	The search identifier provided in the search request, if any.	String	null