DataCapture API Version 6.0

Transcription

1 DataCapture API Version 6.0 1

2 Document Control Document Location An electronic version of this document is available at: and Disclaimer This documentation is draft and just informative and APX & Belpex reserve the right to modify the information and the structure of APX & Belpex DataCapture API 6.0 v2.1. No rights or obligations can be derived from any documentation or information concerning APX DataCapture API 6.0 v2.1 originating from APX and Belpex. 2

3 Contents page Document Control 2 Document Location 2 Revision History Error! Bookmark not defined. Approvals Error! Bookmark not defined. 1 Introduction [Paragraph title] Environments 6 Power NL 6 Belpex 6 2 The DataCapture process [Paragraph title] 7 3 Requesting Data General Protocol File Formats 8 CSV 8 XML & XML Data Format Error codes 9 CSV 9 XML 10 XML Request & Response Specifications Data Format 12 Parameters for orders request 12 Returned data Own Trade Data on contract time 13 Parameters for own trades request 13 Returned Data Own Trade Data on delivery period 16 Parameters for own trades request 16 Returned Data 17 3

4 4.4 All Trades Data 19 Parameters for all trades request 19 Returned data Chargelines 21 Parameters for chargelines request 21 Returned data General matching report 24 Parameters for general matching request 24 Returned data 24 5 Manifest Errors and Reversed Trades [Paragraph title] 26 6 System requirements [Paragraph title] 27 Using an application 27 Using a web browser 27 7 Usage Guidelines [Paragraph title] Making sure you get all trades when using Private Trade Capture 28 Appendix I: Market Segment Identifiers and Instrument Codes 30 Default Market Set 30 APX Power NL 30 Belpex 30 Appendix II: XML output format 31 OrderCapture 31 TradeCapture 32 Chargelinecapture 33 Appendix III: XML2 output format 36 OrderCapture 36 TradeCapture 37 PublicTradeCapture 39 General matching 41 4

5 Error 44 Appendix IV: Error codes and messages 45 5

6 1 Introduction 1.1 [Paragraph title] The DataCapture system is an environment that provides members the ability to quickly and easily capture a range of information. The data available for capture is: Orders in the market; Members own trades by contract time; Members own trades by delivery period; All trades; Chargelines. This document describes the functionality of this DataCapture system that APX and Belpex offer their members, explaining how the system can be used and what information can be retrieved. Chapter 3 describes the process and explains the flow of information and the overall architecture. Chapter 4 contains specific information about the requests for Order & TradeCapture. Chapter 5 contains information about the requests and the responses. Chapter 6 provides information about the test set up for the DataCapture system. Appendix I contains a description of the Platform Identifiers, Market Segment Identifiers and the Instrument codes. Appendix II and III describe the XML and XML2 response specifications. Appendix IV contains a list of error codes and the related messages. 1.2 Environments The DataCapture system is available for the APX Power NL and Belpex markets, which can be reached through the following URLs: Production: Standby: Test: Power NL The following price and volume units are used for the Power NL exchange: Price: Euros per megawatt hour ( /MWh) Volume unit: Megawatt (MW) Belpex The following price and volume units are used for the Belpex exchange: Price: Euros per megawatt hour ( /MWh) Volume unit: Megawatt (MW) 6

7 2 The DataCapture process 2.1 [Paragraph title] Order and Trade information can be captured from the APX & Belpex web server. Access is available either via the Internet or a leased line connection to APX and Belpex. This environment is connected to the central database used by the trading application, thus delivering real-time information. To retrieve the data a request has to be made to a component situated at an APX & Belpex web server. This request can be made by a custom-made member application or by using a standard web browser. The Data Capture process: APX & Belpex Web server APX & Belpex Trading Database Member Data file received File reception and processing Request Request File display in browser Custom-made member application Web browser Back office systems 7

8 3 Requesting Data 3.1 General The system distinguishes five request types. Members can request: Orders in the market; Members own trades by contract time Members own trades by delivery period; All trades. The five types of requests can be gathered from the base URL with the report parameter. The URL for orders is: The URL for private trades by contract time is: The URL for private trades by delivery period is: The URL for all trades is: The URL for the Chargelines report is: The base URL ( differs slightly between our production, standby and member test environments. 3.2 Protocol APX or Belpex will assign username and initial password combinations to the members. Passwords can be changed by logging on to the BackOffice website, (using the DataCapture username and password). Communication with the DataCapture web server is only possible using a Secure Sockets Layer (SSL) connection. Username and password authentication will happen by passing these as parameters within the URL. It is possible to use a custom made application or a standard web browser to request the system for trades. 3.3 File Formats The DataCapture web server currently supports three output formats: 'csv' and two XML formats: 'xml' and xml2. While default output format is 'csv' we strongly recommend using the xml2 output format since the other formats are only maintained for backwards compatibility. CSV The csv format is known by common spreadsheet software (including Microsoft Excel). This comma-separated data will be sent as plain text. In a web browser this will result in the comma separated data being displayed in the browser window. If you want to load this data in your spreadsheet program, save the outputted data to a text-file and open it in your spreadsheet program. XML & XML2 8

9 DataCapture can also return data in two different XML-formats. Specifications of these XML-formats can be found in Appendix II and Appendix III. These formats are especially suited for applications querying the system. 3.4 Data Format The format of numbers returned, are one of three formats: Integer; Numeric, or Decimal. Integers are whole numbers only. Numeric has a floating number of decimal places; the number following the comma in the format indicates the maximum number of decimals. E.g. Numeric (10,3) has a maximum of three decimal places. Decimals have a fixed number of decimal places; the number following the comma in the format indicates the number of decimals. 3.5 Error codes Due to the nature of Internet communication, data can sometimes be interrupted, causing incomplete information to be received. To be able to identify any problems in the transmission each output format employs its own validation method. In addition to communication errors between the member and the DataCapture server, other errors can occur. In this situation an error-code and message will be returned. An explanation of the error codes can be found in Appendix IV. CSV To verify the completeness of received data the CSV-file returns a special footer line. The last line of the returned data does not contain order or trade data but contains information about the request. If a request was successful, the last line will contain a # followed by the number of returned lines (for example if a request returns 24 data-rows, this will be #24), followed by a comma and then followed by a value consisting of the date and time that the database was last updated. By including the last database update time in the footer, users will know what time to use as the next begin time to ensure that no data is missed. Examples: 1) The current date and time is 09:47:10 on the 10 th October The user specifies a begin time of (10 October :45:00) and no end time. The system finds 24 trades between this begin time and end time and will return 24 comma separated data-rows and then a 25 th row containing: #24, Which means the system time of the last database update was (10 October :46:20) at the time of the request. This date time is then used as the new begin time for the next request. If a request resulted in an error, only a footer line will be returned. This line will consist of: #<errorcode>, <error message>. An explanation of the error codes can be found in Appendix IV. 9

10 Examples: a) The username and password combination is unknown to the system The system will return: -11 Authentication not successful. The username & password provided did not match any in our database. In this case contact APX or Belpex to make sure your credentials are valid. b) There was an error in your request and you provided an invalid date time for begin. The system will return: -21, Invalid value for parameter. Parameter 'begin' is not a valid timestamp In this case check the request parameters and try again. c) Due to a technical error the Trade Capture application cannot reach the database. The system will return: -31, A technical error occurred. Please contact the administrator In this case report this to APX or Belpex and provide the exact request with this report. XML The completeness of an XML document can be easily verified by checking whether it is well-formed. Any request that did not experience connection problems returns a well-formed XML document. At least a <response> element will be returned, containing a status, timestamp and msg attribute. On a successful request the status will be 1. In case of an error the status will contain the error code. The timestamp will be the date time the database was last updated. In case of an error the msg attribute will contain the error-message. Example: For some reason the Trade Capture application has been closed for queries. You requested an XML response. The system will return: <?xml version="1.0" encoding="iso "?> <response status="-41" timestamp="" msg="the system is closed"> </response> In this case try again in a little while or inform APX or Belpex who may be able to explain the reason for this closure. XML2 The completeness of an XML document can be easily verified by checking whether it is well-formed. Any request that did not experience connection problems returns a well-formed XML document. At least a <response> element will be returned, containing <header> element with a status, timestamp and msg element. On a successful request the status will be 1. In case of an error the status will contain the error code. The timestamp will be the date time the database was last updated. In case of an error the msg attribute will contain the error-message. 10

11 Example: The report you ve requested doesn t exist. You requested an XML2 response. The system will return: <?xml version="1.0" encoding="iso "?> <Response xsi:nonamespaceschemalocation=" xmlns:xsi=" <Header> <Status>-101</Status> <Message>Report error: Unknown report: chargeline </Message> <Timestamp> T11:11:48Z</Timestamp> </Header> </Response> In this case try again in a little while or inform APX or Belpex who may be able to explain the reason for this closure. Note that the timestamps in the XML2 specifications comply with the XML Date time standard as described here: 11

12 4 Request & Response Specifications 4.1 Data Format Parameters for orders request ID string>&output=<format>&platform=<platform> The table shows the parameters that should be submitted to the DataCapture URL when requesting Orders: Parameter name Description Definition Mandatory Report The report to display Text Yes User User Name as provided by APX / Belpex Text Yes Pass Password as provided by APX / Belpex Text Yes Market Platform Output Allows orders only in specified market segments to be returned Allows orders only in specified platforms to be returned Specifies the output format to be used. Default format is csv Semi-colon separated text string x;y;z;a;b;c Semi-colon separated text string x;y;z;a;b;c Text, either csv, xml or xml2 The platform identifiers, market segment identifiers and the default market set can be found in Appendix I No, omitting or invalid means default market set will be returned No, omitting or invalid means all platforms will be returned No, omitting or invalid for csv format Examples: To retrieve all, submit the following: To retrieve all orders in the APX Power NL Strips Dutch Base Market Segment in CSV format, submit the following: Replace username and password in the URLs above with those provided. Returned data 12

13 The data returned is a snapshot of all the open orders in the market at the time of the request. The information is anonymous due to all the open orders are returned and so that members are not able to identify orders from other members. The following table describes the fields present in the output file. In the case of a CSV response, the fields will be returned in this order. In the XML response, the values will be put in the appropriate fields (see Appendix II and Appendix III for the XML specifications). Field Format Description Instrument Code Text Identifying the contract type & block Market segment Identifier Text The identifier representing the market segment Buy / Sell Flag Text = B or S denoting Buy or Sell Price Decimal (10,2) or null The order price in the appropriate format Volume Numeric (10,3) The Volume in the appropriate format Order ID Integer ID of the order submitted to the market Version Number Integer Version of the order submitted to the market Begintime in GMT Endtime in GMT Date time, YYYY-MM-DD hh:mm:ss Date time, YYYY-MM-DD hh:mm:ss Begin time of the first delivery period of the order or null for forward trades End time of the last delivery period of the order or null for forward trades Note that the timestamps in the XML2 specifications comply with the XML Date time standard as described here: Example file (CSV): 09JAN08 - PTE 76,NL_PTE,B,10,10, ,0, :45:00, :00:00 09JAN08 - PTE 76,NL_PTE,S,12,10, ,0, :45:00, :00:00 09JAN08 - PTE 77,NL_PTE,B,10,10, ,0, :00:00, :15:00 09JAN08 - PTE 77,NL_PTE,S,12,10, ,0, :00:00, :15:00 09JAN08 - PTE 78,NL_PTE,B,10,10, ,0, :15:00, :30:00 09JAN08 - PTE 79,NL_PTE,B,10,10, ,0, :30:00, :45:00 #6, Order IDs and Version Numbers orders submitted into the Market have a unique Order ID and a version number. If an order is modified, or partially matched then the version number is changed, but the original order ID remains the same. E.g. an order for 100MW is submitted in to the market, and is allocated an order ID = 1234 and version=0. If the order is partially matched for 25MW, then the remaining pending order ID is still 1234 but the version changes to 1, and the volume is now 75MW. Be advised: this report will not return any auction trade data. 4.2 Own Trade Data on contract time Parameters for own trades request egin time>&end=<endtime>&market=<market segment ID string>&account=<integer string>&output=<format>&platform=<platform> 13

14 The table shows the parameters that should be included in the request made to the web server to retrieve your own trades that have been traded within a specific date time range and for some or all market segments, and some or all of your position accounts. Parameter name Description Definition Mandatory Report The report to display Text Yes User User Name as provided by APX / Belpex Text Yes Pass Password as provided by APX / Belpex Text Yes Begin End Market Platform Account Output Trades transacted within this period will be retrieved. (GMT) Allows trades only in specified market segments to be returned Allows orders only in specified platforms to be returned It is possible to specify specific position account(s). Only trades on this account will be retrieved. Specifies the output-format to be used. Default format is csv Date time, YYYYMMDDhh mmss Date time, YYYYMMDDhh mmss Semicolon separated string x;y;z;a;b;c Semicolon separated string x;y;z;a;b;c Semicolon separated Integer string n;n;n;n;n;n Text, either csv, xml or xml2 Note that the begin/end parameters relate to the time the trade was created in the system, NOT the time the trade delivers. The market segment identifiers and the default market set can be found in Appendix I. Position account identifiers will be provided to individual members on request. Yes No, omitting this parameter means until now No, omitting or invalid means default market set will be returned No, omitting or invalid means all platforms will be returned No, omitting or invalid parameter means all accounts No, omitting or invalid for csv format Examples: To retrieve own trades matched at a time greater than 23:10:10 on 9 th June 2012 GMT until present time in XML2 format, submit the following: 0&output=xml2 To retrieve own trades for just one position account, with account ID 2, in APX DAM Hourly (Belpex DAM Hourly) only, traded at a time greater than 16:10:10 on 17 th September 2012 GMT until a time equal to or less than 18:19:07 on 17 th September 2012 GMT, submit the following: 0&end= &market=NL_DAM1H&account=2 Replace username and password in the URLs above with those provided. Returned Data 14

15 The following table describes the fields present in the output file generated by the own trades request. In the case of a CSV response, the fields will be returned in this order. In the XML response, the values will be put in the appropriate fields (see Appendix II and Appendix III for the XML specifications). Field Format Description Contract ID Integer Uniquely identifying the trade and equivalent to ID in Contract book in Trading Application Instrument Code Text Identifying the trade type & block Order number Integer Refers to the order number used in the Trading Application Own Position Account Integer Contains the ID of the position account used by the requesting member Position account of the counterparty Integer For bilateral markets will contain the ID of the position account used by the counterparty, all other markets, field will be null Market Segment Identifier Text The identifier representing the market segment Buy / Sell Flag Text = B or S denoting Buy or Sell Begintime in GMT Endtime in GMT Date time, YYYY-MM-DD hh:mm:ss Date time, YYYY-MM-DD hh:mm:ss Begintime of the first delivery period in a trade, or null for forward trades Endtime of the last delivery period in a trade or null for forward trades Volume Numeric (10,3) A positive number for the trading volume expressed in the appropriate format Price Decimal (10,2) or null The actual trade price in the appropriate format Time of trade GMT Date time, YYYY-MM-DD hh:mm:ss The actual date and time the trade was done LoginID Text The name of the user that submitted the bid or offer. For bilateral trades, this field will be null Reversed Contract ID Integer If this record is for a Trade that reverses an erroneous trade then this field will contain the Contract ID of the Trade reversed, otherwise it will be null (see section 5.6) Note that the timestamps in the XML2 specifications comply with the XML Date time standard as described here: Requesting your own trades will bring back all trades made by you as the Member, including the login that transacted the trade. The login field for bilateral trades will only be populated where the member initiated the bilateral order and not when the member confirmed the order. 15

16 For Members who will be regularly polling the system to retrieve their trades on an ongoing basis, it is recommended that the users submit a 'begin' Date Time equal to the Date Time returned by the system as the used end time, and leave the 'end' Date Time blank. This will ensure that no trades are missed and will keep the load on the system to a minimum. Example for request for own trades on contract time (CSV): ,NL 1H H24, ,725,,NL_DAM1H,B, :00:00, :00:00,150,16, :35:37,APX050674Q, ,NL 1H H24, ,725,,NL_DAM1H,B, :00:00, :00:00,150,16, :35:37,APX050674Q, ,NL 1H H24, ,725,,NL_DAM1H,B, :00:00, :00:00,150,16, :35:37,APX050674Q, #3, Own Trade Data on delivery period Parameters for own trades request begin time>&end=<endtime>&market=<market segment ID string>&account=<integer string>&output=<format>&platform=<platform> The table shows the parameters that should be included in the request made to the web server to retrieve your own trades that have the delivery period within a specific datetime range and for some or all market segments, and some or all of your position accounts. Parameter name Description Definition Mandatory Report The report to display Text Yes User User Name as provided by APX / Belpex Text Yes Pass Password as provided by APX / Belpex Text Yes Begin End Market Platform Account Output Trades with a delivery period within this period will be retrieved. (GMT) Allows orders only in specified market segments to be returned Allows orders only in specified platforms to be returned It is possible to specify specific position account(s). Only trades on this account will be retrieved. Specifies the output-format to be used. Default format is csv Date time, YYYYMMDDhh mmss Date time, YYYYMMDDhh mmss Semicolon separated string x;y;z;a;b;c Semicolon separated string x;y;z;a;b;c Semicolon separated Integer string n;n;n;n;n;n Text, either csv, xml or xml2 Yes No, omitting this parameter means until now No, omitting or invalid means default market set will be returned No, omitting or invalid means all platforms will be returned No, omitting or invalid parameter means all accounts No, omitting or invalid for csv format 16

17 Note that the begin/end parameters relate to the time the trade delivers, NOT the time the trade was created in the system. The market segment identifiers and the default market set can be found in Appendix I. Position account identifiers will be provided to individual members on request. Examples: To retrieve own trades matched with a delivery time greater than 23:10:10 on 16 th September 2012 GMT until present time, submit the following: To retrieve own trades for just one position account, with account ID 2, in the APX DAM Hourly only, with a delivery period within 23:10:10 on 9 th June 2012 and 03:19:07 on 10 th June 2012 in CSV format, submit the following: 10&end= &market=NL_DAM1H&account=2&output=csv Replace username and password in the URLs above with those provided. Returned Data The following table describes the fields present in the output file generated by the own trades request. In the case of a CSV response, the fields will be returned in this order. In the XML response, the values will be put in the appropriate fields (see Appendix II and Appendix III for the XML specifications). 17

18 Field Format Description Contract ID Integer Uniquely identifying the trade and equivalent to ID in Contract book in Trading Application Instrument Code Text Identifying the trade type & block Order number Integer Refers to the order number used in the Trading Application Own Position Account Integer Contains the ID of the position account used by the requesting member Position account of the counterparty Integer For bilateral markets will contain the ID of the position account used by the counterparty, all other markets, field will be null Market Segment Identifier Text The identifier representing the market segment Buy / Sell Flag Text = B or S denoting Buy or Sell Begintime in GMT Endtime in GMT Date time, YYYY-MM-DD hh:mm:ss Date time, YYYY-MM-DD hh:mm:ss Begintime of the first delivery period in a trade, or null for forward trades Endtime of the last delivery period in a trade or null for forward trades Volume Numeric (10,3) A positive number for the trading volume expressed in the appropriate format Price Decimal (10,2) or null The actual trade price in the appropriate format Time of trade GMT Date time, YYYY-MM-DD hh:mm:ss The actual date and time the trade was done LoginID Text The name of the user that submitted the bid or offer. For bilateral trades, this field will be null Reversed Contract ID Integer If this record is for a Trade that reverses an erroneous trade then this field will contain the Contract ID of the Trade reversed, otherwise it will be null (see section 5.6) Note that the timestamps in the XML2 specifications comply with the XML Datetime standard as described here: Requesting your own trades will bring back all trades made by you as the Member, including the login that transacted the trade. The login field for bilateral trades will only be populated where the member initiated the bilateral order and not when the member confirmed the order. For Members who will be regularly polling the system to retrieve their trades on an ongoing basis, it is recommended that the users submit a 'begin' DateTime equal to the DateTime returned by the system as the used endtime, and leave the 'end' DateTime blank. This will ensure that no trades are missed and will keep the load on the system to a minimum. 18

19 Example for request for own trades on delivery period (CSV): ,NL 1H H01, ,725,,NL_DAM1H,B, :00:00, :00:00,150,16.5, :30:32,APX120180A, ,NL 1H H01, ,725,,NL_DAM1H,B, :00:00, :00:00,150,16.5, :30:32,APX120180A, ,NL 1H H01, ,725,,NL_DAM1H,B, :00:00, :00:00,150,16.5, :30:32,APX120180A, #3, All Trades Data Parameters for all trades request me>&end=<endtime>&market=<market segment ID String>&output=<format>&platform=<platform> The table shows the parameters that should be included in the request made to the web server to retrieve all trades traded within a specific datetime range and for some or all market segments: Parameter name Description Definition Mandatory Report The report to display Text Yes User User Name as provided by APX / Belpex Text Yes Pass Password as provided by APX / Belpex Text Yes Begin End Market Platform Output Trades transacted at a time greater than this time will be retrieved (GMT) Trades transacted at a time equal to or before this time within this period will be retrieved (GMT) Allows orders only in specified market segments to be returned Allows orders only in specified platforms to be returned Specifies the output format to be used. Default format is csv Datetime YYYYMMDDhh mmss Datetime YYYYMMDDhh mmss Semicolon separated string x;y;z;a;b;c Semicolon separated string x;y;z;a;b;c Text, either csv, xml or xml2 Yes No, omitting this parameter means until now No, omitting or invalid means default market set will be returned No, omitting or invalid means all platforms will be returned No, omitting or invalid for csv format Note that the begin/end parameters relate to the time the order was created, NOT the time the trade delivers. The market segment identifiers and the default market set can be found in Appendix I. 19

20 Examples: To retrieve all trades traded at a time greater than 23:10:10 on 18 th September 2012 GMT until present time, submit the following: To retrieve all trades matched at a time greater than 23:10:10 on 9 th June 2012 GMT until a time equal to or less than 03:19:07 on 10 th June 2012 GMT in XML format, submit the following: &end= &output=xml To retrieve only working day next week and weekend trades for NL 1H at a time greater than 23:10:10 on 18 th September 2012 GMT until present time in CSV format, submit the following: &market=NL_1H &output=csv Replace username and password in the URLs above with those provided. Note that the timestamps in the XML2 specifications comply with the XML Datetime standard as described here: For members who will be regularly polling the system to retrieve all trades on an ongoing basis, it is recommended that the users submit a 'begin' DateTime equal to the DateTime returned by the system as the used endtime, and leave the 'end' DateTime blank. This will ensure that no trades are missed and will keep the load on the system to a minimum. Returned data The following table describes the columns present in the output file generated by the public trades request. In the case of a CSV response, the fields will be returned in this order. In the XML response, the values will be put in the appropriate fields (see Appendix II and Appendix III for the XML specifications). Field Format Description Contract ID Integer Uniquely identifying the trade Instrument Code Text Identifying the trade type & block Market Segment Identifier Text Identifying the market segment type Buy / Sell Text Contains a B for buying or a S for selling. Begintime in GMT Endtime in GMT Date time, YYYY-MM-DD hh:mm:ss Date time, YYYY-MM-DD hh:mm:ss Begintime of the first delivery period in a trade or null for forward trades Endtime of the last delivery period in a trade or null for forward trades 20

21 Volume Numeric (10,3) A positive number for the trading volume expressed in the appropriate format Price Decimal (10,2) The actual trade price in the appropriate format Time of trade GMT Date time, YYYY-MM-DD hh:mm:ss The actual date and time the trade was done. Reversed Contract ID Integer If this record is for a Trade that reverses an erroneous trade then this field will contain the Contract ID of the Trade reversed, otherwise it will be null. (see section 5.6) Note that the timestamps in the XML2 specifications comply with the XML Datetime standard as described here: Example file (CSV): ,NL 1H H24,NL_DAM1H,B, :00:00, :00:00,150,16, :35:37, ,NL 1H H24,NL_DAM1H,B, :00:00, :00:00,150,16, :35:37, ,NL 1H H24,NL_DAM1H,B, :00:00, :00:00,150,16, :35:37, #3, Chargelines Parameters for chargelines request _M>&begin=<date/month>&end=<date/month>&chargecodes=<charge_code_ID_string>&status=< F or P>&output=<format>&platform=<platform> The table shows the parameters that should be submitted to the DataCapture URL when requesting the chargelines request: Parameter name Description Definition Mandatory User Username as provided by APX / Belpex Text Yes Pass Password as provided by APX / Belpex Text Yes Type = D for daily or Type of the statement to request to retrieve = W for weekly data for = M for monthly Yes Begin End Chargelines for statements with this date/month or later will be returned. Chargelines for statements with this date/month or earlier will be returned Daily / Weekly = YYYYMMDD Monthly =YYYYMM Daily / Weekly = YYYYMMDD Monthly =YYYYMM Yes No, omitting this parameter means end is the same as begin 21

22 charge codes Status Platform Output It is possible to specify specific charge code(s) 1. Only chargelines with these charge code(s) will be retrieved To filter whether only chargelines on final or preliminary statements are returned Allows orders only in specified platforms to be returned Specifies the output format to be used. Default format is csv Semicolon separated Integer string n;n;n;n;n;n = F or = P Semicolon separated string x;y;z;a;b;c Text, either csv, xml or xml2 No, omitting this parameter means all charge codes No, omitting means all chargelines will be returned No, omitting or invalid means all platforms will be returned No, omitting or invalid for csv format Examples: To retrieve all chargelines for the final daily statements from March 1 st 2004 till March 31 st 2004, submit the following: &end= &status=F Replace username and password in the URL above with those provided. To retrieve all chargelines for the monthly statements of March 2004 with the charge codes or 10021, submit the following: &chargecodes=10021 Returned data The data returned is a snapshot of the chargelines in the system at the time of the request. The following table describes the fields present in the output file: 22

23 Field Format Description Chargeline ID Integer (10) Uniquely identifying chargeline identifier Statement Number Integer (10) ID number of the statement the chargeline belongs to Settlement Period Settlement period of the Weekly: Date YYYY-MM-DD statement Type W Type of the statement this chargeline belongs to. Weekly Position Account ID Integer (10) Identifier of the position account for this chargeline, or null Position Account Name String Name of the position account for this chargeline, or null Contract ID Integer (10) Identifier of the contract this chargeline belongs to, or null Instrument Code String Instrument code, or null Charge code Integer (10) Charge code for this chargeline Description String Description for this chargeline Amount Numeric (10,4) Total amount of the charge of this chargeline Price Numeric (14,3) Price per volume or null Total Volume Numeric (14,3) Volume in MWh or null Volume per unit Numeric (10,3) MW or null Charge or Credit 'Charge' or 'Credit' Whether this is a charge or a credit Fee Numeric (5,4) The applicable fee or null VAT Numeric (5,4) VAT rate or null Final Invoice Number String VAT invoice number, or null Example file: ,36749, ,W,726,APX , ,NL 1H H24,11010,Energy Sales,2400,16,150,150,Credit,,, ,36749, ,W,726,APX , ,NL 1H H24,11020,Fee contracted Energy sales,21,,150,150,charge,.14,, ,36749, ,W,726,APX , ,NL 1H H24,11030,19% VAT on Energy sales,456,16,150,150,credit,,.19, ,36749, ,W,726,APX , ,NL 1H H24,11034,19% VAT on Fees Energy sales,3.99,,150,150,charge,.14,.19, #4, The statement ID and the final invoice number are not the same. Each chargeline will have a statement ID which indicates which chargelines belong to which statement. Chargelines on preliminary statements will not have a final invoice number. When a preliminary statement goes final, the final invoice number will be allocated. The final invoice number will be the same as appears on the VAT invoice on the back-office website. When submitting a request with the status parameter set to F, only those Chargelines with a final invoice number will be returned. If the status is set to P, then only those chargelines without a final invoice number will be returned. If the status parameter is omitted, then all will be returned. 23

24 4.6 General matching report Parameters for general matching request utput=<format> The table shows the parameters that should be submitted to the DataCapture URL when requesting the NL Power auction general matching results: Parameter name Description Definition Mandatory Report The report to display Text Yes User User Name as provided by APX Text Yes Pass Password as provided by APX Text Yes Market Semicolon separated Allows orders only in specified market string segments to be returned x;y;z;a;b;c Output Specifies the output format to be used. Default format in csv Text, either csv, xml or xml2 No, omitting or invalid means all platforms will be returned Yes Example file: To retrieve the general matching results: Replace username and password in the URLs above with those provided. Returned data The data returned is the general matching results for the applicable market segment. The following table describes the fields present in the output file. In the XML2 response, the values will be put in the appropriate fields (see Appendix III for the XML2 specifications). Field Format Description Market Segment identifier Text The identifier representing the market segment Time Date time, YYYY-MM-DD hh:mm:ss Time of the auction Delivery start Date time, YYYY-MM-DD hh:mm:ss Time the delivery period atarts Instrument Text Identifying the trade type & block MCP Decimal (10,2) or null Market Clearing Price MCV Numeric (10,3) Market Clearing Volume Note that the timestamps in the XML2 specifications comply with the XML and Date standard as described here: 24

25 Example file (CSV): A_1HR_T, :43:02, :00:00,1H ,0,0 A_1HR_T, :43:02, :00:00,1H ,0,0 A_1HR_T, :43:02, :00:00,1H ,0,0 A_1HR_T, :43:02, :00:00,1H ,0,0 A_1HR_T, :43:02, :00:00,1H ,0,0 A_1HR, :44:26, :00:00,1H ,30,625 A_1HR, :44:26, :00:00,1H ,32,545 A_1HR, :44:26, :00:00,1H ,32,545 A_1HR, :44:26, :00:00,1H ,32,545 A_1HR, :44:26, :00:00,1H ,27,625 A_1HR, :44:26, :00:00,1H ,27,625 A_1HR, :44:26, :00:00,1H ,27,627 A_1HR, :44:26, :00:00,1H ,27,967 A_1HR, :44:26, :00:00,1H ,32,575 A_1HR, :44:26, :00:00,1H ,34,575 A_1HR, :44:26, :00:00,1H ,34,575 A_1HR, :44:26, :00:00,1H ,34,575 A_1HR, :44:26, :00:00,1H ,32,725 A_1HR, :44:26, :00:00,1H ,33,725 A_1HR, :44:26, :00:00,1H ,34,725 A_1HR, :44:26, :00:00,1H ,29,1015 A_1HR, :44:26, :00:00,1H ,34,750 A_1HR, :44:26, :00:00,1H ,34,750 A_1HR, :44:26, :00:00,1H ,34,750 A_1HR, :44:26, :00:00,1H ,34,750 A_1HR, :44:26, :00:00,1H ,34,750 A_1HR, :44:26, :00:00,1H ,34,750 A_1HR, :44:26, :00:00,1H ,33,750 A_1HR, :44:26, :00:00,1H ,32,750 #29,

26 5 Manifest Errors and Reversed Trades 5.1 [Paragraph title] If a Trade has been made in error, then it is cancelled out by entering a reverse trade, i.e. a trade with the same price & volume, but with the Buyer and Seller reversed. The reversing trade will be linked to the original trade by the inclusion of the original trade s contract ID as an additional field in the reversing trade s record. In the All Trades file, a manifest error of this kind will normally result in two reversed trades, as for each cleared trade, there exists two trades in the system: Buyer to APX & Belpex and APX & Belpex to Seller. 26

27 6 System requirements 6.1 [Paragraph title] Using an application Members can connect their own systems to the APX & Belpex DataCapture system making use of the standard https protocol. All modern programming languages include libraries to submit web requests and process the response. Please refer to the documentation of your programming language of choice. Using a web browser It is possible to use a standard web browser to submit a request to the DataCapture system. The web browser will receive the comma-separated data and display it in the browser-window. This can then be saved or copied to a spreadsheet program. 27

28 7 Usage Guidelines 7.1 [Paragraph title] In order to ensure the availability and responsiveness of the Datacapture system, the following usage limits have been implemented: Trade Capture Public Minimal Interval request: 10 seconds Maximum records per request: 1000 Trade Capture Private Minimal Interval request: 10 seconds Maximum records per request: 100 Order Capture Minimal Interval request: 10 seconds Chargeline Minimal Interval request: 10 seconds Maximum records per request: 1000 If these restrictions are violated an error code and error message can be returned. An explanation of the error codes can be found in Appendix IV 7.2 Making sure you get all trades when using Private Trade Capture To ensure system responsiveness and performance while at the same time making sure no trades are missed when running the various reports, the following strategy can be followed: Every trade capture response contains a timestamp. Assuming no end time was specified in the request, the timestamp can be interpreted as the used end time. All trades done between the specified begin time and the returned timestamp are by definition contained in the response. In order to guarantee this the timestamp will typically be seconds behind the current time. If an end time is being specified within the request, this should then be used as the begin time within the next request. By using the returned timestamp as the begin parameter for the next request you will always get every trade. 28

29 Example: Assume first request is done January 9 th 2008 at 14:50: This request gives the following response: ,NL 1H H24, ,725,,NL_DAM1H,B, :00:00, :00:00,50,16, :45:12,APX050674Q, ,NL 1H H24, ,725,,NL_DAM1H,B, :00:00, :00:00,150,16, :46:43,APX050674Q, #2, This means that exactly two trades ( & ) were done between 14:40:00 and 14:48:06. To make sure no data is lost, the timestamp in the response should be used in the next request, which is done January 9 th 2008 at 14:55:00: This request gives the following response: ,NL 1H H24, ,725,,NL_DAM1H,B, :00:00, :00:00,150,16, :49:36,APX050674Q, ,NL 1H H24, ,725,,NL_DAM1H,B, :00:00, :00:00,150,16, :51:17, APX050674Q, #2, This response contains the trade , which was done at 14:49:36, before the first request was performed. By using the timestamp of the first request as the begin time of the second request this trade is not missed. 29

30 Appendix I: Market Segment Identifiers and Instrument Codes Default Market Set If no markets are specified in the request, information regarding all markets will be returned. APX Power NL The following overview displays the available APX Power NL market segments with the corresponding instruments codes and market segment identifiers. Name Market Segment DAY-AHEAD MARKET Segment Code Instrument Code Market Segment Identifier NL 1H H17 APX DAM Hourly NL_DAM1H INTRADAY NL 1H 17DEC07-1H 24 NL_1H Belpex The following overview displays the available Belpex market segments with the corresponding instruments codes and market segment identifiers. Name Market Segment Segment Code Instrument Code Market Segment Identifier Belpex DAM Belpex DAM Hourly BE 1H H17 BE_DAM1H Belpex CIM Belpex ID 1H BE ID 08SEP14 1H - 19 BE_1H 30

31 Appendix II: XML output format OrderCapture XML Schema <?xml version="1.0" encoding="iso "?> <xs:schema xmlns:xs=" elementformdefault="qualified" attributeformdefault="unqualified"> <xs:element name="response"> <xs:sequence> <xs:element name="ord" minoccurs="0" maxoccurs="unbounded"> <xs:attribute name="id" type="xs:positiveinteger" use="required"/> <xs:attribute name="nm" type="xs:string" use="required"/> <xs:attribute name="ms" type="xs:string" use="required"/> <xs:attribute name="s" use="required"> <xs:simpletype> <xs:restriction base="xs:string"> <xs:length value="1"/> </xs:restriction> </xs:simpletype> </xs:attribute> <xs:attribute name="bt" type="xs:string" use="required"/> <xs:attribute name="et" type="xs:string" use="required"/> <xs:attribute name="p" type="xs:decimal" use="required"/> <xs:attribute name="v" type="xs:decimal" use="required"/> <xs:attribute name="ver" type="xs:int" use="required"/> </xs:sequence> <xs:attribute name="status" type="xs:int" use="required"/> <xs:attribute name="timestamp" type="xs:string" use="required"/> <xs:attribute name="msg" type="xs:string" use="required"/> </xs:schema> Example <?xml version="1.0" encoding="iso "?> <response status="1" timestamp=" " msg=""> <ord id="10345" nm="4h " ms="s_4hb" s="b" bt=" :00:00" et=" :00:00" p="12.00" v="100" ver="2" /> <ord id="10346" nm="4h " ms="s_4hb" s="s" bt=" :00:00" et=" :00:00" p="13.04" v="50" ver="0" /> <ord id="10347" nm="2h a" ms="s_2hb" s="s" bt=" :00:00" et=" :00:00" p="12.02" v="75" ver="1" /> </response> Explanation of attributes <response> status Status of the response. If the request was a success the status will be 1, otherwise it will be one of the error codes. timestamp Timestamp of the last replication. msg Status message. In case of an error a textual error message will appear here 31

32 <ord> id nm ms s bt et p v ver orderid instrument code marketsegmentidentifier side begintime endtime price volume orderversion TradeCapture XML Schema <?xml version="1.0" encoding="iso "?> <xs:schema xmlns:xs=" elementformdefault="qualified" attributeformdefault="unqualified"> <xs:element name="response"> <xs:sequence> <xs:element name="trd" minoccurs="0" maxoccurs="unbounded"> <xs:attribute name="cid" type="xs:positiveinteger" use="required"/> <xs:attribute name="nm" type="xs:string" use="required"/> <xs:attribute name="id" type="xs:positiveinteger" use="required"/> <xs:attribute name="pa" type="xs:positiveinteger" use="required"/> <xs:attribute name="cpa" type="positiveinteger-or-empty"/> <xs:attribute name="ms" type="xs:string" use="required"/> <xs:attribute name="s" use="required"> <xs:simpletype> <xs:restriction base="xs:string"> <xs:length value="1"/> </xs:restriction> </xs:simpletype> </xs:attribute> <xs:attribute name="bt" type="xs:string" use="required"/> <xs:attribute name="et" type="xs:string" use="required"/> <xs:attribute name="v" type="xs:decimal" use="required"/> <xs:attribute name="p" type="xs:decimal" use="required"/> <xs:attribute name="t" type="xs:string" use="required"/> <xs:attribute name="l" type="xs:string" use="required"/> <xs:attribute name="rcid" type="positiveinteger-or-empty" use="required"/> </xs:sequence> <xs:attribute name="status" type="xs:int"/> <xs:attribute name="timestamp" type="xs:string"/> <xs:attribute name="msg" type="xs:string"/> <xs:simpletype name="positiveinteger-or-empty"> <xs:union membertypes="xs:positiveinteger empty-string"/> </xs:simpletype> <xs:simpletype name="empty-string"> <xs:restriction base="xs:string"> <xs:enumeration value=""/> </xs:restriction> </xs:simpletype> </xs:schema> Example 32

33 <?xml version="1.0" encoding="iso "?> <response status="1" timestamp=" " msg=""> <trd cid="12756" nm="hh " id="1010" pa="7" cpa="" ms="s_hh" s="s" bt=" :30:00" et=" :00:00" v="200" p="15.50" t=" :45:23" l="trader2" rcid="" /> <trd cid="12760" nm="2h b" id="1016" pa="8" cpa="" ms="s_2hb" s="s" bt=" :00:00" et=" :00:00" v="120" p="250.00" t=" :45:23" l="trader2" rcid="" /> <trd cid="12766" nm="hh " id="1019" pa="8" cpa="" ms="s_hh" s="b" bt=" :30:00" et=" :00:00" v="100" p="23.40" t=" :15:17" l="trader1" rcid="" /> <trd cid="12767" nm="2h b" id="1020" pa="8" cpa="" ms="s_2hb" s="b" bt=" :00:00" et=" :00:00" v="120" p="250.00" t=" :15:17" l="operator" rcid="12760" /> </response> Explanation of attributes <response> status Status of the response. If the request was a success the status will be 1, otherwise it will be one of the error codes. timestamp Timestamp of the last replication. msg Status message. In case of an error a textual error message will appear here <trd> cid nm id pa cpa ms s bt et v p t l rcid contractid instrumentcode orderid own positionaccount counterparty positionaccount marketsegmentidentifier side begintime endtime volume price tradetime username reversed contractid Chargelinecapture <?xml version="1.0" encoding="iso "?> <xs:schema xmlns:xs=" elementformdefault="qualified" attributeformdefault="unqualified"> <xs:element name="response"> <xs:sequence> <xs:element name="cl" minoccurs="0" maxoccurs="unbounded"> <xs:attribute name="cli" type="xs:positiveinteger" use="required"/> <xs:attribute name="si" type="xs:positiveinteger" use="required"/> <xs:attribute name="sp" type="xs:string" use="required"/> <xs:attribute name="typ" use="required"> <xs:simpletype> <xs:restriction base="xs:string"> <xs:length value="1"/> </xs:restriction> </xs:simpletype> </xs:attribute> <xs:attribute name="pa" type="positiveinteger-or-empty" use="required"/> <xs:attribute name="pan" type="xs:string" use="required"/> <xs:attribute name="cid" type="positiveinteger-or-empty" use="required"/> <xs:attribute name="ic" type="xs:string" use="required"/> <xs:attribute name="cc" type="xs:positiveinteger" use="required"/> 33