REST API version 1

The REST API is used for downloading matching sets of outage information from the POCP. For uploading please see the XML API reference or CSV API reference.

Calling Convention

Each endpoint should be called with the documented HTTP method. The URL should be constructed by putting the supplied URL on the end of /api/rest/v1/ e.g. for the category_list URL you would use /api/rest/v1/category_list

Authentication

Authentication is done by supplying your API as part of each request. If you don't have an API key, you need to request one from Transpower.

You can supply the API key for each request either as a query parameter api_key in the URL e.g. 

/api/rest/v1/category_list?api_key=your_api_key
or if you prefer, as an HTTP header X-API-Key.

If you fail to provide an API key, or you provide an invalid API key, the response will be an HTTP 403.

Errors

Errors other than authentication are returned with HTTP status code 400. The body of the response contains further information about the error.

Changes to this documentation

Changes to this document will be logged at the bottom of this page.

Resources

GET search

Description

Searches for outages in the POCP system

This behaves in the same way the search interface in the main web application works.

Note that there is a limit of 5,000 results per query. This exists to prevent excessive load on the database, queries should always be appropriately designed to avoid coming near this limit. In the event the query is too large the system will raise an error.

Parameters
Field name Description Type Default
owner_outage_id Filer by owner outage ID string empty string (i.e. no outage ID constraint)
block Filter by outage block string empty string (i.e. no outage block constraint)
date_option Whether the date range is absolute or relative string, either "absolute" or "relative" relative
start Active on or after this date (absolute only) string in the format YYYY-MM-DDTHH:MM:SS or YYYY-MM-DD today's date
end Active on or before this date (absolute only) string in the format YYYY-MM-DDTHH:MM:SS or YYYY-MM-DD empty string (i.e. not constraint on results)
next_unit Whether relative is in days or weeks string, either "days" or "weeks" days
next_count How many days/weeks ahead to search for Integer n/a
planning_status Only outages matching this planning status. This field may be repeated to provide multiple planning statuses 0 or more strings tentative and confirmed
org Constrain to only these owners (specified using owner_id). This field may be repeated to provide multiple owner IDs 0 or more integers no value (i.e. no constraint on owner)
category Only outages matching this category. This field may be repeated to provide multiple categories. 0 or more strings empty list (i.e. no category constraint)
grid_points Only outages matching these grid points. comma separated list of strings empty string (i.e. no grid point constraint)
modified_since Outage has been created or uploaded since this date string in the format YYYY-MM-DDTHH:MM:SS or YYYY-MM-DD empty string (i.e. not constraint on results)
Example Request https://pocp.redspider.co.nz/api/rest/v1/search?next_count=14&api_key=my_api_key
Example Response 
{
    "query": {
        "category": [],
        "grid_points": null,
        "planning_status": [
            "tentative",
            "confirmed"
        ],
        "end": null,
        "next_count": 14,
        "query_at": "2015-01-12T15:22:42",
        "assessment_status": [],
        "date_option": "relative",
        "modified_since": null,
        "start": null,
        "so_status": null,
        "org": [],
        "region": null,
        "group_id": null,
        "owner_outage_id": null,
        "next_unit": null,
        "block": null
    },
    "result": [
        {
            "grid_points": "ARI_Sth",
            "nature": null,
            "mw_remain": "0.00",
            "mvar": "0.00",
            "mw_loss": "27.00",
            "planning": "confirmed",
            "owner": "Mighty River",
            "category": "generation",
            "end": "2015-01-12T12:00:00",
            "owner_outage_id": "53691",
            "modified": "2014-12-22T14:33:43",
            "pci_issue": false,
            "owner_id": 17,
            "type": "continuous",
            "start": "2015-01-12T07:30:00",
            "block": "ARI_5",
            "pocp_int_id": "205588"
        },
        ...
    ]
}
Other examples

Absolute date range

https://pocp.redspider.co.nz/api/rest/v1/search?date_option=absolute&start=2015-01-01&end=2015-01-14&api_key=my_api_key

Modified since

https://pocp.redspider.co.nz/api/rest/v1/search?modified_since=2015-01-12T00:00:00&api_key=my_api_key

GET category_list

Description Returns the list of valid catagories in the POCP system
Parameters None
Example Request /api/rest/v1/category_list
Example Response 
{
    "generation": "Generation", 
    "transmission": "Transmission", 
    "direct_connection": "Direct connection", 
    "distribution": "Distribution", 
    "embedded_generation": "Embedded generation"
}

GET planning_status_list

Description Returns the list of valid planning statuses in the POCP system
Parameters None
Example Request /api/rest/v1/planning_status_list
Example Response 
{
    "tentative": "Tentative", 
    "confirmed": "Confirmed", 
    "cancelled": "Cancelled", 
    "completed": "Completed"
}

GET owner_list

Description Returns the list of asset owners in the POCP system
Parameters None
Example Request /api/rest/v1/owner_list
Example Response 
[
    {
        "owner_id": 29, 
        "type": "asset_owner", 
        "slug": "alinta", 
        "name": "Alinta"
    }, 
    {
        "owner_id": 18, 
        "type": "asset_owner", 
        "slug": "contact-energy", 
        "name": "Contact Energy"
    }, 
    {
        "owner_id": 19, 
        "type": "asset_owner", 
        "slug": "ena", 
        "name": "ENA"
    }, 
    {
        "owner_id": 16, 
        "type": "asset_owner", 
        "slug": "genesis", 
        "name": "Genesis"
    }, 
    {
        "owner_id": 23, 
        "type": "asset_owner", 
        "slug": "meug", 
        "name": "MEUG"
    }, 
    {
        "owner_id": 17, 
        "type": "asset_owner", 
        "slug": "mercury", 
        "name": "Mercury"
    }, 
    {
        "owner_id": 20, 
        "type": "asset_owner", 
        "slug": "meridian", 
        "name": "Meridian"
    }, 
    {
        "owner_id": 30, 
        "type": "asset_owner", 
        "slug": "nz_steel", 
        "name": "NZ Steel"
    }, 
    {
        "owner_id": 24, 
        "type": "asset_owner", 
        "slug": "nzas", 
        "name": "NZAS"
    }, 
    {
        "owner_id": 27, 
        "type": "asset_owner", 
        "slug": "nova-energy", 
        "name": "Nova Energy"
    }, 
    {
        "owner_id": 25, 
        "type": "asset_owner", 
        "slug": "powerco", 
        "name": "PowerCo"
    }, 
    {
        "owner_id": 21, 
        "type": "asset_owner", 
        "slug": "powernet", 
        "name": "Powernet"
    }, 
    {
        "owner_id": 28, 
        "type": "asset_owner", 
        "slug": "tilt", 
        "name": "Tilt Renewables"
    }, 
    {
        "owner_id": 26, 
        "type": "asset_owner", 
        "slug": "top-energy", 
        "name": "Top Energy"
    }, 
    {
        "owner_id": 12, 
        "type": "asset_owner", 
        "slug": "transpower", 
        "name": "Transpower"
    }, 
    {
        "owner_id": 22, 
        "type": "asset_owner", 
        "slug": "trustpower", 
        "name": "Trustpower"
    }
]

Changes

12 Jan 2015
Improved description and notes about querying relative vs absolute. Improved example response to include additional fields not previously documented.