technical article

PV API Procurement: Specify JSON or XML for Both Endpoints

November 17, 2026Updated: November 17, 20267 min readFact Checked
Cinn Song

Cinn Song

Founder & Chief Solutions Architect

PV API Procurement: Specify JSON or XML for Both Endpoints

TL;DR

Specify JSON or XML for both APIs. Require explicit formats, site and calculation inputs, a traceable weather-file handoff and separate endpoint tests. CSV is documented only for discovery; specify calculation CSV exports separately.

Specify JSON or XML explicitly for both Solar Dataset Query V2 and PVWatts V8; CSV is documented only for discovery. Require site coordinates, calculation inputs, weather-file traceability and endpoint-specific acceptance checks. Treat any calculation CSV export as a separately specified application deliverable.

Summary

Specify JSON or XML explicitly for both Solar Dataset Query V2 and PVWatts V8; CSV is documented only for discovery. Require site coordinates, calculation inputs, weather-file traceability and endpoint-specific acceptance checks. Treat any calculation CSV export as a separately specified application deliverable.

Key Takeaways

  • JSON and XML are documented for both endpoints; CSV is listed only for Solar Dataset Query V2.
  • Both endpoints require an explicit response format and document no default format.
  • PVWatts V8 can use a valid discovery file_id; omit dataset when using that identifier.
  • Record weather-source details and distance, keeping discovery radius miles distinct from returned distance meters.
  • Specify calculation inputs, timeframe and units: monthly energy and hourly power are different output fields.
  • Verify both endpoint parsers, the weather-file handoff, warnings and invalid-input handling before acceptance.

Specify JSON or XML Across Climate Discovery and PV Production Calculations

Summary: Specify JSON or XML for both Solar Dataset Query V2 and PVWatts V8. Both document these response formats; CSV is listed only for discovery. Require explicit format selection, site coordinates, calculation inputs and weather-file traceability. Verify each endpoint separately before accepting the integration.

1. Choose a format supported by both endpoints

PV API Procurement: Specify JSON or XML for Both Endpoints — Detailed functional anatomy

For a procurement specification covering climate-data discovery and PV production calculations, require one shared response format: JSON or XML. Solar Dataset Query V2 lists json, xml and csv, while PVWatts V8 lists json and xml. Both describe format as required, without a default. Their request URLs place the selected format after the endpoint version. Solar Dataset Query V2; PVWatts V8

Recommended contract wording is: “The integration shall explicitly request JSON for both discovery and calculation, or XML for both where required by the receiving system. CSV discovery support shall be specified separately.” Choose between JSON and XML according to the buyer’s receiving software and acceptance requirements. The documented format lists do not establish a performance advantage for either choice.

CSV remains a documented discovery option. However, its appearance in Solar Dataset Query V2 does not establish CSV support for PVWatts V8. If a bidder proposes CSV calculation delivery, ask whether this is an application-generated export and require a separate export specification. Do not accept discovery-format support as verification of the calculation interface.

2. Specify the discovery-to-calculation handoff

PV API Procurement: Specify JSON or XML for Both Endpoints — Detailed system operations and maintenance

Solar Dataset Query V2 requires an API key, latitude, longitude and response format. It returns information about available climate files, including identifiers, coordinates, distance and weather-data source. For a dataset without a result, the documented response contains null and a warning. Recommend requiring the application to retain these warnings alongside the discovery result. Solar Dataset Query V2

PVWatts V8 accepts either site latitude and longitude or a file_id. A file_id must be a valid identifier returned by Solar Dataset Query V2. When specifying that identifier, the documentation says not to pass dataset. For an auditable handoff, recommend recording the selected discovery identifier and submitting it explicitly to the calculation endpoint. PVWatts V8

The search settings also need explicit treatment. Discovery documents radius in miles, while its returned distance is in meters. It states that radius=0 finds the closest stations regardless of distance and that all=1 requires a positive radius. Although the illustrated request combines zero radius with all=1, procurement acceptance should follow the parameter rule and test a positive radius when requesting all stations. Solar Dataset Query V2

Recommend asking the bidder to show the selected weather record and its distance before calculation approval. A successful discovery response alone should not serve as the buyer’s acceptance of that record for the project.

3. Define calculation inputs and output meanings

A common serialization format does not replace the calculation specification. PVWatts V8 requires nameplate capacity, module type, system losses, array type, tilt and azimuth, together with the location or climate-file selection and API access parameters. Recommend requiring a project input schedule that identifies each submitted value and distinguishes deliberate selections from documented defaults. PVWatts V8

Specify output granularity as well. PVWatts V8 defaults to monthly results and accepts timeframe=hourly. Its monthly AC and DC outputs are energy values in kWhac and kWhdc; hourly AC and DC outputs are power values in Wac and Wdc. Monthly arrays run from January through December. Recommend including these field names, units and ordering in the interface acceptance sheet. PVWatts V8

For weather traceability, request retention of station_info, including the weather-data source and solar-resource filename. The documented response also includes received inputs, errors, warnings, service version and SSC library information. Recommend storing the relevant calculation response with each reviewed estimate so the buyer can inspect the modeled configuration and its provenance. PVWatts V8

4. Accept the integration through endpoint-specific checks

Recommend requiring the bidder to demonstrate discovery and calculation separately in the selected format, then demonstrate the handoff between them. Check discovery identifiers, missing-dataset warnings and the selected climate record. For calculation, check the submitted inputs, returned station information, requested timeframe and output units.

Require separate parser checks for each endpoint, even when both use JSON or XML. Discovery describes available climate files; PVWatts returns simulation results and calculation metadata. A shared format should therefore be a contract choice alongside explicit field mapping. Solar Dataset Query V2; PVWatts V8

Both documents describe HTTP 422 for missing or invalid parameters and direct users to the response’s errors section. Recommend including an invalid-input case in acceptance testing and verifying that the application reports the error rather than presenting it as a production estimate. Both also state a limit of 1,000 requests per hour; ask the bidder to explain how the proposed request schedule respects it. Solar Dataset Query V2; PVWatts V8

The acceptance boundary is a working discovery and simulation interface. PVWatts V8 documents predicted production outputs. For a procurement decision involving guaranteed project generation, request the separate project-specific evidence and contractual terms supporting that guarantee.

FAQ

Should the contract require JSON or XML?

Require either as the shared format, selected to suit the receiving software. Both endpoints document JSON and XML.

Can CSV be specified for both APIs?

CSV is documented for Solar Dataset Query V2, but it is not listed among PVWatts V8 response formats. Specify any application-generated calculation CSV export separately.

Can the integration omit the format selection?

Both documents mark format as required and list no default. Require explicit selection in each request.

How can a discovered climate file be selected for calculation?

Pass its valid discovery identifier as PVWatts V8 file_id. The documentation says not to pass dataset with file_id.

Does radius=0 restrict discovery to the project location?

No. It selects the closest stations regardless of distance. Inspect the returned distance before approving the weather record.

What happens when discovery finds no data for a dataset?

Solar Dataset Query V2 documents a null output for that dataset and a warning. Require the application to preserve and report it.

Are hourly AC values reported as energy?

PVWatts V8 documents hourly ac in Wac. Monthly ac_monthly and annual ac_annual are documented in kWhac.

What should invalid-input acceptance testing check?

Both documents describe HTTP 422 for invalid or missing parameters. Verify that the application reads the errors section and reports the failure.

Quality Score:96/100

About the Author

Cinn Song

Cinn Song

Founder & Chief Solutions Architect

Cinn Song founded SOLARTODO LIMITED and leads its smart-city infrastructure engineering — from solar, storage and integrated smart poles to the company's push into physical-AI city edge nodes: pole-mounted edge computing, vertical LLMs for smart cities, drone-based O&M with autonomous battery swapping, robotic maintenance, and high-speed counter-UAS interception. Since 2010, he has directed turnkey EPC + BOT delivery across 50+ countries, including telecom monopole supply for national grid operators, off-grid solar street-lighting for African municipalities, and integrated smart-pole programs for Gulf smart cities.

View All Posts

Cite This Article

APA

Cinn Song. (2026). PV API Procurement: Specify JSON or XML for Both Endpoints. SOLARTODO. Retrieved from https://solartodo.com/knowledge/should-the-pv-software-integration-specify-json-or-xml-for-both-climate-data-discovery-and-production-calculations

BibTeX
@article{solartodo_should_the_pv_software_integration_specify_json_or_xml_for_both_climate_data_discovery_and_production_calculations,
  title = {PV API Procurement: Specify JSON or XML for Both Endpoints},
  author = {Cinn Song},
  journal = {SOLARTODO Knowledge Base},
  year = {2026},
  url = {https://solartodo.com/knowledge/should-the-pv-software-integration-specify-json-or-xml-for-both-climate-data-discovery-and-production-calculations},
  note = {Accessed: 2026-11-17}
}

Published: November 17, 2026 | Available at: https://solartodo.com/knowledge/should-the-pv-software-integration-specify-json-or-xml-for-both-climate-data-discovery-and-production-calculations

Subscribe to Our Newsletter

Get the latest solar energy news and insights delivered to your inbox.

View All Articles
PV API Procurement: Specify JSON or XML for Both Endpoints | SOLARTODO