REST API Endpoints
Host Environment URLs
Here are the host environment URLs for the MarketSuite® REST APIs:
UAT
Production
The authentication tokens for the above environments must come from the corresponding UAT/Prod authentication server.
Upload File
The Upload File Request is designed to support uploading files to the APX MarketSuite®, primarily files for ISO scheduling data. The response is a string representing the file unique identifier (GUID). This identifier can be used to retrieve the file using the Get File method. This identifier can also be used to retrieve the status of all data submitted (for CAISO/ERCOT submissions) or the exception data (other regions) using the GetStatus method.
If the file uploaded is the ISO Scheduling Data xml file, the method does XSD validation of the file and will reject any XML file submissions which are not valid. The ISO Scheduling Data CSV file is also validated for format. The returned error message will include the validation details.
The maximum request size for files uploaded through this Web service is 10MB.
Endpoint (POST): /fileRegistry/file
Parameters
These parameters must be POST-ed to the endpoint above as URL-encoded form data.
| Field | Description |
|---|---|
| location | ISO code. Values include PJM, ISONE, MISO, SPP, NYISO, MRTU (used for CAISO), TX (used for ERCOT). |
| participant | MarketSuite® participant API code. Often, this is the ISO Scheduling code, preceded by some relevant text to make it unique. Please confirm the correct code with your APX Account manager. |
| intervalBegin | DateTime value marking the start of the interval for the file. The value is in XML DateTime format. This is the date that will be associated with the file when it is registered. The time component should always be 00:00, e.g. 2019-11-18T00:00:00 |
| intervalEnd | DateTime value marking the end of the interval for the file. This should be the interval_begin + one day. Note that the data in the file may extend past this date. |
| fileType | Type of file being uploaded. Valid fileTypes for the regions PJM, ISONE, MISO, SPP, NYISO are: · APX_SchedulingData_CSV (See CSV Spec for format details) · APX_SchedulingData_XML Valid fileTypes for the regions TX (ERCOT) and MRTU (CAISO) are: · APX_NonXmkrt_SchedulingDataCSV (See CSV Spec for format details) · APXBidsandOffers (See XML Spec for format details) |
| source | Name of the source. For ISO Scheduling data submissions, use ‘Client’ |
| rendition | Some file types have more than one rendition. Those are named sets that look identical but represent different sets. For example: “DA” and ”RT” or “Initial”, ”recalc”, and “final”. For ISO Scheduling data submissions, use ‘DAM’ or ‘RTM’. |
| file | Byte array representing the compressed data file. |
Return Value
The return value is a string representing the file unique identifier. This identifier can be used to retrieve the file using the GetFile method and to retrieve the ISO scheduling data exception details of the file using the GetStatus method.
GetStatus
The GetStatus Request allows the user to retrieve the exception details of scheduling data uploaded to the APX MarketSuite®. A unique identifier called the File handle is returned from the Upload File Request. This unique identifier is used in the GetStatus Request to retrieve the exception details of the specified file data.
Each exception is returned in the results. Some individual rows may generate more than one exception, in which case one row per exception is returned.
The response of the GetStatus Request is in the form of a compressed XML file.
For CAISO/ERCOT, the returned XML complies with the schema definition ScheduleData.xsd. The full specification appears in the section “APX ISO Scheduling API specification.”
For PJM/ISONE/SPP/MISO/NYISO, the returned XML complies with the schema definition ScheduleData.xsd. The full specification appears in the section “APX ISO Scheduling API specification - xMarket”. Note that in the future other schemas will be returned, depending on the type of file uploaded.
Endpoint (GET): /fileRegistry/file/{fileHandle}/status
Parameters
These parameters must be POST-ed to the endpoint above as URL-encoded form data.
| Field | Description |
|---|---|
| fileHandle | Unique identifier of the file for which status is being requested. |
Return Value
A byte array containing the compressed data. The format of the file will be the same as the file that was uploaded: requesting the status of an XML file upload will return results in XML, and a CSV upload will have results in CSV.
Note: The GetStatus Request is recommended for gathering status upon a file upload. The response file contains an overall status and record level statuses.
-
FileStatus – reflects the overall status of the file upload. Below is the list of fileStatuses.
FileStatus File load in progress File loaded into system, records successfully retrieved File loaded into system, no records found Error in processing file File does not exist Unrecognized status retrieved from APX MarketSuite transformation; please contact support - Status – reflects the status of each bidoffer/resource parameter/bilateral schedule record.
GetScheduleData
The GetScheduleData request retrieves schedule data from the APX MarketSuite®. From many aspects it can be thought of as the API version of the Checkout application. The requested data sets may include trades, bid-offer or resource parameters, pre-market (APX image or ISO image) or post-market (awards and final schedules and trades).
The data may be requested in either XML or CSV format, and in either case will be in the same format as for uploads, with some additional info for status of the data.
The response of the GetScheduleData Request is in the form of a compressed XML file.
For CAISO/ERCOT, the returned XML complies with the schema definition ScheduleData.xsd. The full specification appears in the section “APX ISO Scheduling API specification.”
For PJM/ISONE/SPP/MISO/NYISO, the returned XML complies with the schema definition ScheduleData.xsd. The full specification appears in the section “APX ISO Scheduling API specification - xMarket”. Note that in the future other schemas will be returned, depending on the type of file uploaded.
Endpoint (PUT): /fileRegistry/getScheduleData/{fileName}
Parameters
These parameters must be POST-ed to the endpoint above as URL-encoded form data.
| Field | Description |
|---|---|
| fileName (in endpoint) | The name of the file that will be created in the zip archive that is sent back as the return parameter. Clients can specify the file name and then use it to extract the contents of the zip archive. |
| region | ISO code. Values include PJM, ISONE, MISO, SPP, NYISO, MRTU (used for CAISO), TX (used for ERCOT). |
| marketParticipants | List of MarketSuite® participant codes for which the method should return data. Often, this is the ISO Scheduling code, preceded by some relevant text to make it unique. Please confirm the correct code with your APX Account manager. |
| marketStage | Market stage of the requested data |
| marketStatus | ‘Pre’ or ‘Post’—pre-market data with its status, or post-market awards. NOTE: Post-market awards only available for CAISO(MRTU) and ERCOT (TX). Post-market awards for other regions coming soon. |
| firstIntervalBegin | Required parameter that specifies the starting date for which data is being requested. |
| lastIntervalEnd | For PJM, ISONE, SPP, MISO, and NYISO required parameter that specifies the ending date for which data is being requested. If not given, default is tradeDate+1 day. Note: Not allowed for CAISO(MRTU) or ERCOT(TX), where each request may only be for one day. |
| applications | ‘BidsOffers’, ‘BilateralSchedules’, and/or ‘ResourceParameters’—applications for which data is being requested. Note: For PJM, ISONE, SPP, MISO, and NYISO, request is limited to ‘BilateralSchedule’ OR BidsOffers/ResourceParameters. |
| format | CSV or XML. XML will comply with the schema definition ScheduleData.xsd. CSV will be same format used for upload. |
Return Value
A byte array containing the compressed data file.
File List
The File List Request is designed to retrieve a list files which can be downloaded from the APX MarketSuite®. The response returns an array of filelistitems.
Endpoint (PUT): /fileRegistry/listFiles
Parameters
These parameters must be POST-ed to the endpoint above as URL-encoded form data.
| Field | Description |
|---|---|
| region | ISO code. Values include PJM, ISONE, MISO, SPP, NYISO, MRTU (used for CAISO), TX (used for ERCOT). |
| participant | MarketSuite® participant API code. Often, this is the ISO Scheduling code, preceded by some relevant text to make it unique. Please confirm the correct code with your APX Account manager. |
| fileType | Type of file included in the list. |
| source | Data source of the files to search for. |
| rendition | Some file types have more than one rendition. Those are named sets that look identical but represent different sets. For example: “DA” and ”RT” or “Initial”, ”recalc”, and “final”. |
| latestVersionOnly | Flag indicating whether or not to list the most recent version of a file. True means list the most recent version only. False means list all versions. The default is true. |
Return Value
A json array of filelistitems. filelistitems include the following properties:
| Field | Description |
|---|---|
| location | The name of the ISO or more granular location designation if one was specified when the file was registered. |
| participant | The name of the participant associated with this file |
| intervalBegin | DateTime value of interval_begin that was specified when the file was uploaded or otherwise registered. This is not necessarily true for the content of the file. |
| intervalEnd | Date time value of interval_end that was specified when the file was uploaded or otherwise registered. This is not necessarily true for the content of the file. |
| source | Data source of the files to search for. |
| rendition | Some file types have more than one rendition. Those are named sets that look identical but represent different sets. For example: “DA” and ”RT” or “Initial”, ”recalc”, and “final”. |
| fileType | Type of file included in the list. |
| fileVersion | The version of the file. |
| fileStructureVersion | The version of the structure of the file |
| fileFormat | The format of the file (CSV, XML, MDEF, etc.) |
| fileHandle | The handle of the file used to retrieve the file in the GetFile method |
| createDate | The create date of the file |
File List Since
The File List Since Request is designed to retrieve a list files which can be downloaded from the APX MarketSuite® which have changed since the specified date. The response returns an array of filelistitems.
Endpoint (PUT): /fileRegistry/listFilesSince
Parameters
These parameters must be POST-ed to the endpoint above as URL-encoded form data.
| Field | Description |
|---|---|
| region | ISO code. Values include PJM, ISONE, MISO, SPP, NYISO, MRTU (used for CAISO), TX (used for ERCOT). |
| participant | MarketSuite® participant API code. Often, this is the ISO Scheduling code, preceded by some relevant text to make it unique. Please confirm the correct code with your APX Account manager. |
| fileType | Type of file included in the list. |
| source | Data source of the files to search for. |
| rendition | Some file types have more than one rendition. Those are named sets that look identical but represent different sets. For example: “DA” and ”RT” or “Initial”, ”recalc”, and “final”. |
| latestVersionOnly | Flag indicating whether or not to list the most recent version of a file. True means list the most recent version only. False means list all versions. The default is true. |
| watermarkDate | DateTime value indicating the last date/time that files were fetched, results in the new list including only files that have changed since that date/time (the creation date is greater than and not equal to the watermark date). The value is in XML DateTime format which includes the GMT offset. |
| newWatermarkDate | Output DateTime value to use as the watermarkdate in the next GetListSince call. The value is the maximum createdate of the files returned in the list. The value is in XML DateTime format which includes the GMT offset. |
Return Value
A json array of filelistitems. filelistitems include the following properties:
| Field | Description |
|---|---|
| location | The name of the ISO or more granular location designation if one was specified when the file was registered. |
| participant | The name of the participant associated with this file |
| intervalBegin | DateTime value of interval_begin that was specified when the file was uploaded or otherwise registered. This is not necessarily true for the content of the file. |
| intervalEnd | Date time value of interval_end that was specified when the file was uploaded or otherwise registered. This is not necessarily true for the content of the file. |
| source | Data source of the files to search for. |
| rendition | Some file types have more than one rendition. Those are named sets that look identical but represent different sets. For example: “DA” and ”RT” or “Initial”, ”recalc”, and “final”. |
| fileType | Type of file included in the list. |
| fileVersion | The version of the file. |
| fileStructureVersion | The version of the structure of the file |
| fileFormat | The format of the file (CSV, XML, MDEF, etc.) |
| fileHandle | The handle of the file used to retrieve the file in the GetFile method |
| createDate | The create date of the file |
File Download
The File Download Request is designed to retrieve a specific file from the APX MarketSuite®. The file is returned in a zip file byte array.
Endpoint (GET): /fileRegistry/file/{fileHandle}
Parameters
| Field | Description |
|---|---|
| fileHandle (in endpoint) | Unique string used to identify the file in the APX MarketSuite®. |
| file_name | Output parameter, the name of the file inside the compressed byte array |
Return Value
A byte array containing the compressed data file.
Report Download
The Report Download Request is designed to retrieve data from the APX MarketSuite® in the specified format. The data file is returned in a zip file byte array.
Endpoint (PUT): /reporting/getReport
Parameters
| Field | Description |
|---|---|
| reportPath | The report-specific path for the report to run. See Appendix C for reports and paths. |
| [key/value pairs] | Parameter name/value pairs required to run the report. These are the report-specific parameters that will be unique for each report. See Appendix C for report-specific parameters (keys). |
| reportFormat | Output file format – CSV, Excel, and XML. |
Return Value
A byte array containing the compressed data file.