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_keyor 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 |
|
||||||||||||||||||||||||||||||||||||||||||||||||||||
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.