XML API version 2

The XML API is used for uploading outages to the POCP. For downloading please see the REST API reference.

Authentication

Version 1 authentication for uploading is done by supplying a username and password via HTTP Basic. This continues to function in v2.

Version 2 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/xml/v2/upload?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.

Testing

Testing uploads for validity without any risk of committing them can be done by uploading to:

/api/xml/v2/test

No API key or other authentication is required to perform this test, and no changes will be committed to the database. A simple test can be performed by creating a valid file and then doing:

curl -F xmlfile=@my-data.xml https://pocp.redspider.co.nz/api/xml/v2/test

The output will contain details about the upload in XML, including any warnings.

To perform a test using your browser, go to the form at /api/xml/v2/test_form and upload there.

XML upload format

Note: For easiest integration, the use of the cURL utility (http://curl.sourceforge.net/) is recommended for uploading of XML files via HTTP.

The following is an example planned outage using the XML format. All fields are linked to their respective descriptions.

<?xml version="1.0"?>
<pocp>
<outage_update>
<outage>
<id> TEST_0001 </id>
<planning_status> tentative </planning_status>
<category> generation </category>
<time_type> continuous </time_type>
<nature> pso </nature>
<block> CCT_241_GYM_WCC </block>
<coordination_notes> Test comment </coordination_notes>
<start> 2014-06-25T12:00:00 </start>
<end> 2014-06-25T13:00:00 </end>
<recall> 02:00 </recall>
<mwatt_remaining> 10.00 </mwatt_remaining>
<mwatt_lost> 5.00 </mwatt_lost>
<mvar_remaining> 3.00 </mvar_remaining>
<gp> CCT </gp>
<gp> GYM </gp>
<reason> Reason for outage </reason>
<asset_description> Description of this asset </asset_description>
<group> 102839 </group>
</outage>
</outage_update>
</pocp>

Tag specifics

<pocp>

The root tag for a POCP upload, all POCP data or operations are contained inside. This tag is required.

<outage_update>

All outages contained within this tag are updates to the POCP. This tag is required, you can have more than one per file if desired but in practice there should only be one and all outages should be contained within this tag.

<outage>

Defines the current state of a single outage, uniquely identified (for this asset owner) by the <id> tag. This tag is optional - if no updates are being done the parent outage_update tag can be empty.

<id>

Contains an ID for the outage, unique to the asset owner (multiple asset owners may define the same ID, the POCP defines its own globally unique ID for each outage but that isn't relevant to this process). The ID is an arbitrary string of the format [A-Z0-9a-z_-]+. For example, TEST_0001.

This tag is required for all outages. Only one <outage> tag with a given ID may be specified per <outage_update> .

<planning_status>

Contains the current asset owner planning status for the outage. This planning status is one of:

  • tentative
  • confirmed
  • cancelled
  • completed
Outages may not enter complete status if they are not yet equal to or past their end date.

If the asset owner uploads an outage update that does not contain the data for a given outage, and that outage has not yet past its end date, that outage will automatically be set to cancelled. This is to retain compatibility with v1, however asset owners are encouraged to always explicitly set an outage to cancelled or complete as necessary.

If the outage end date is past now (in the upload) and the current outage status is one of cancelled or completed, it is not valid to set the planning_status to anything other than cancelled or completed. If an attempt is made to do so, the planning status change will be ignored and a warning generated. Any other changes to the outage will be processed as normal.

This tag is required.

<category>

Contains the asset category. Options are:

  • generation
  • transmission
  • direct_connection
  • distribution
  • embedded_generation

distribution and embedded_generation are only available in API version 2.

This tag is required.

<time_type>

Specifies whether the outage is continuous (i.e. between the start and end times without a break) or daily (between the start and end times for each day in the date range). Options are:

  • continuous
  • daily

This tag is required.

<nature>

Specifies the nature of the outage. This is typically only applicable to transmission outages. Options are:

  • pso
  • rs
  • sca
  • oth
  • ope
  • clo

This tag is optional, but if provided may not be empty.

<block>

The outage block is defined as a set of elements separated by an underscore (_).

For generator outages, the format is more specific and must be [Asset Code][underscore][unit] or [Asset Code][underscore][station]. Failure to meet this validation condition will generate a warning, but will not fail the upload.

This tag is required.

In version 1 this tag was called plant instead. plant may still be used in v2.

<coordination_notes>

Specifies an arbitrary text comment to assist coordination. XML entities must be escaped as normal, the length of the notes is restricted to 4096 characters.

In version 1 this tag was called comment instead. comment may still be used in v2.

<start>

Specifies the start date and time of the outage in standard XML time format YYYY-MM-DDTHH:MM:SS, for example 2014-06-25T12:00:00.

All times are interpreted in the Pacific/Auckland timezone, i.e. localtime in NZ standard or daylight-savings time as appropriate.

This tag is required.

<end>

Specifies the end date and time of the outage in standard XML time format YYYY-MM-DDTHH:MM:SS, for example 2014-06-25T12:00:00.

The end time must be later than the matching <start> .

All times are interpreted in the Pacific/Auckland timezone, i.e. localtime in NZ standard or daylight-savings time as appropriate.

This tag is required.

In version 1 this time was required to be no earlier than 7 days prior to the date of the upload - i.e. it was not possible to update an outage with an end date more than a week in the past. This restriction no longer applies.

<recall>

Specifies the recall time for the outage in hours and minutes as HH:MM, for example 02:00

This field is optional.

In version 1 this field had an undocumented maximum limit of 839 hours. This limit no longer applies.

This tag is optional.

<mwatt_remaining>

Specifies the megawatts remaining while the outage is active. Must be a positive number with no more than 2 decimal places. If the value is not known, the tag should be omitted.

Note: when specifying the decimal value, a leading zero is required if the value is below 1.00, i.e. 0.25 is valid but .25 is not.

For load, this tag defines the peak load still drawn while the outage is active.

This tag is optional.

<mwatt_lost>

Specifies the megawatts lost from normal output while the outage is active. Must be a positive number. If the value is not known the tag should be omitted.

For load this tag defines the load no longer drawn while the outage is active.

This tag is optional.

<mvar_remaining>

Specifies the megavar remaining while the outage is active. Must be a positive number.

For load, this tag defines the megavar lost, not megavar remaining, due to the difficulty of estimating the later.

<confidential>

This tag is deprecated, the validator will still accept it however specifying true will result in an error.

This tag is now optional. If specified, this tag must contain the string value false.

<gp>

A grid point involved in the current outage. As many as necessary may be specified by repeating the tag.

The grid point must match the master list stored within POCP. Failure to meet this condition will result in a warning, but will not fail the upload.

This tag is required, and can be repeated.

<reason>

Specifies a reason for the outage. The reason is an arbitrary string with a 4,096 character length limit.

This tag is optional.

<asset_description>

Specifies a description for the asset the outage is occurring on. This is primarily intended for embedded generation or other assets that many market participants may be unfamiliar with. The description is an arbitrary string with a 4,096 character length limit.

This tag is optional

<group>

Specifies a group ID, allowing the outage to be displayed with other outages in the same group. The group ID is an arbitrary string.

In most cases it is expected that asset owners will copy a group ID provided by Transpower for a particular outage, however asset owners are welcome to use their own group IDs to group their own asset outages.

Asset owners are encouraged to give their own group IDs a unique prefix to avoid accidentally matching a group provided by another asset owner.

This tag is optional.

Upgrading from v1

No changes are needed from v1 to v2 - all new tags are optional, and all changed tags will still accept their old names. An asset owner who does not change any aspect of their upload will only generate warnings at this time.

When you are ready to make the move to v2, the following changes should be made:

Rename <plant> to <block>
The name of this tag has changed in v2, although <plant> continues to be supported in v2.
Rename <comment> to <coordination_notes>
The name of this tag has changed in v2, although <comment> continues to be supported in v2.
Add <reason>
Add the tag <reason> if desired. This tag is optional
Add <asset_description>
Add the tag <asset_description> if desired. This tag is optional
Add <group>
Add the tag <group> if desired. This tag is optional
Remove <confidential>
Remove the tag <confidental>. This tag is no longer functional
Send correct status for past outages
Ensure that outages past their end date are only ever sent to completed or cancelled, not tentative or confirmed

You should also change the endpoint from /pocp_xml.php to /api/xml/v2/upload?api_key=your_api_key and request your API key from the Transpower System Operator.

Change log

2016-09-12
Removed rule requiring the first three letters of the block match one of the gp entries.