Aquisição de API fotovoltaica: especifique JSON ou XML para ambos os endpoints
Cinn Song
Founder & Chief Solutions Architect

Especifique explicitamente JSON ou XML tanto para Solar Dataset Query V2 como para PVWatts V8; CSV está documentado apenas para a pesquisa de dados. Exija coordenadas do local, parâmetros de cálculo, rastreabilidade dos ficheiros meteorológicos e verificações de aceitação específicas para cada endpoint. Trate qualquer exportação CSV dos cálculos como uma entrega da aplicação com especificação separada.
Resumo
Especifique explicitamente JSON ou XML tanto para Solar Dataset Query V2 como para PVWatts V8; CSV está documentado apenas para a pesquisa de dados. Exija coordenadas do local, parâmetros de cálculo, rastreabilidade dos ficheiros meteorológicos e verificações de aceitação específicas para cada endpoint. Trate qualquer exportação CSV dos cálculos como uma entrega da aplicação com especificação separada.
Principais pontos
- JSON e XML estão documentados para ambos os endpoints; CSV está listado apenas para Solar Dataset Query V2.
- Ambos os endpoints exigem um formato de resposta explícito e não documentam nenhum formato predefinido.
- PVWatts V8 pode utilizar um file_id válido obtido na pesquisa; omita dataset ao utilizar esse identificador.
- Registe os detalhes da fonte meteorológica e a distância, distinguindo as milhas do raio de pesquisa dos metros da distância devolvida.
- Especifique os parâmetros de cálculo, o intervalo temporal e as unidades: a energia mensal e a potência horária são campos de saída diferentes.
- Verifique os analisadores de ambos os endpoints, a transferência do ficheiro meteorológico, os avisos e o tratamento de parâmetros inválidos antes da aceitação.
Especifique JSON ou XML na pesquisa de dados climáticos e nos cálculos de produção fotovoltaica
Resumo: Especifique JSON ou XML tanto para Solar Dataset Query V2 como para PVWatts V8. Ambos documentam estes formatos de resposta; CSV está listado apenas para a pesquisa. Exija a seleção explícita do formato, coordenadas do local, parâmetros de cálculo e rastreabilidade dos ficheiros meteorológicos. Verifique cada endpoint separadamente antes de aceitar a integração.
1. Escolha um formato suportado por ambos os endpoints

Para uma especificação de aquisição que abranja a pesquisa de dados climáticos e os cálculos de produção fotovoltaica, exija um formato de resposta comum: JSON ou XML. Solar Dataset Query V2 lista json, xml e csv, enquanto PVWatts V8 lista json e xml. Ambos descrevem format como obrigatório, sem valor predefinido. Os respetivos URLs de pedido colocam o formato selecionado após a versão do endpoint. Solar Dataset Query V2; PVWatts V8
A redação contratual recomendada é: “A integração deverá solicitar explicitamente JSON tanto para a pesquisa como para o cálculo, ou XML para ambos quando exigido pelo sistema recetor. O suporte de CSV na pesquisa deverá ser especificado separadamente.” Escolha entre JSON e XML de acordo com o software recetor do comprador e os requisitos de aceitação. As listas de formatos documentados não estabelecem uma vantagem de desempenho para nenhuma das opções.
CSV continua a ser uma opção documentada para a pesquisa. No entanto, a sua presença em Solar Dataset Query V2 não comprova o suporte de CSV em PVWatts V8. Se um proponente apresentar uma proposta de entrega dos cálculos em CSV, pergunte se se trata de uma exportação gerada pela aplicação e exija uma especificação de exportação separada. Não aceite o suporte de formatos de pesquisa como verificação da interface de cálculo.
2. Especifique a transferência entre a pesquisa e o cálculo

Solar Dataset Query V2 exige uma chave de API, latitude, longitude e formato de resposta. Devolve informações sobre os ficheiros climáticos disponíveis, incluindo identificadores, coordenadas, distância e fonte dos dados meteorológicos. Para um conjunto de dados sem resultado, a resposta documentada contém null e um aviso. Recomenda-se exigir que a aplicação conserve estes avisos juntamente com o resultado da pesquisa. Solar Dataset Query V2
PVWatts V8 aceita a latitude e a longitude do local ou um file_id. Um file_id tem de ser um identificador válido devolvido por Solar Dataset Query V2. Ao especificar esse identificador, a documentação indica que não se deve enviar dataset. Para uma transferência auditável, recomenda-se registar o identificador selecionado na pesquisa e enviá-lo explicitamente ao endpoint de cálculo. PVWatts V8
As definições de pesquisa também exigem tratamento explícito. A pesquisa documenta radius em milhas, enquanto a distance devolvida está em metros. Indica que radius=0 encontra as estações mais próximas independentemente da distância e que all=1 exige um raio positivo. Embora o pedido ilustrado combine um raio zero com all=1, a aceitação no âmbito da aquisição deve seguir a regra do parâmetro e testar um raio positivo ao solicitar todas as estações. Solar Dataset Query V2
Recomenda-se pedir ao proponente que apresente o registo meteorológico selecionado e a respetiva distância antes da aprovação do cálculo. Uma resposta de pesquisa bem-sucedida, por si só, não deve constituir a aceitação desse registo pelo comprador para o projeto.
3. Defina os parâmetros de cálculo e o significado dos resultados
Um formato de serialização comum não substitui a especificação do cálculo. PVWatts V8 exige potência nominal, tipo de módulo, perdas do sistema, tipo de arranjo, inclinação e azimute, juntamente com a seleção da localização ou do ficheiro climático e os parâmetros de acesso à API. Recomenda-se exigir um quadro de parâmetros do projeto que identifique cada valor enviado e distinga as seleções deliberadas dos valores predefinidos documentados. PVWatts V8
Especifique também a granularidade dos resultados. PVWatts V8 utiliza resultados mensais por predefinição e aceita timeframe=hourly. Os seus resultados mensais de CA e CC são valores de energia em kWhac e kWhdc; os resultados horários de CA e CC são valores de potência em Wac e Wdc. As matrizes mensais abrangem janeiro a dezembro. Recomenda-se incluir estes nomes de campos, unidades e ordem na ficha de aceitação da interface. PVWatts V8
Para garantir a rastreabilidade meteorológica, solicite a conservação de station_info, incluindo a fonte dos dados meteorológicos e o nome do ficheiro de recurso solar. A resposta documentada também inclui os parâmetros recebidos, erros, avisos, versão do serviço e informações da biblioteca SSC. Recomenda-se armazenar a resposta de cálculo relevante com cada estimativa analisada, para que o comprador possa inspecionar a configuração modelada e a sua proveniência. PVWatts V8
4. Aceite a integração através de verificações específicas para cada endpoint
Recomenda-se exigir que o proponente demonstre a pesquisa e o cálculo separadamente no formato selecionado e, em seguida, demonstre a transferência entre ambos. Verifique os identificadores da pesquisa, os avisos de conjuntos de dados ausentes e o registo climático selecionado. Para o cálculo, verifique os parâmetros enviados, as informações da estação devolvidas, o intervalo temporal solicitado e as unidades dos resultados.
Exija verificações separadas do analisador de cada endpoint, mesmo quando ambos utilizam JSON ou XML. A pesquisa descreve os ficheiros climáticos disponíveis; PVWatts devolve resultados de simulação e metadados de cálculo. Por conseguinte, um formato comum deve ser uma escolha contratual acompanhada de um mapeamento explícito dos campos. Solar Dataset Query V2; PVWatts V8
Ambos os documentos descrevem HTTP 422 para parâmetros ausentes ou inválidos e encaminham os utilizadores para a secção de erros da resposta. Recomenda-se incluir um caso de parâmetros inválidos nos testes de aceitação e verificar se a aplicação comunica o erro em vez de o apresentar como uma estimativa de produção. Ambos também indicam um limite de 1000 pedidos por hora; peça ao proponente que explique como a programação de pedidos proposta respeita esse limite. Solar Dataset Query V2; PVWatts V8
O âmbito da aceitação é uma interface funcional de pesquisa e simulação. PVWatts V8 documenta resultados de produção prevista. Para uma decisão de aquisição que envolva produção garantida do projeto, solicite as evidências específicas do projeto e as condições contratuais separadas que sustentam essa garantia.
Perguntas frequentes
O contrato deve exigir JSON ou XML?
Exija qualquer um dos dois como formato comum, selecionado de acordo com o software recetor. Ambos os endpoints documentam JSON e XML.
É possível especificar CSV para ambas as APIs?
CSV está documentado para Solar Dataset Query V2, mas não está listado entre os formatos de resposta de PVWatts V8. Especifique separadamente qualquer exportação CSV dos cálculos gerada pela aplicação.
A integração pode omitir a seleção do formato?
Ambos os documentos assinalam o formato como obrigatório e não indicam nenhum valor predefinido. Exija uma seleção explícita em cada pedido.
Como se pode selecionar para cálculo um ficheiro climático encontrado na pesquisa?
Envie o respetivo identificador válido da pesquisa como file_id de PVWatts V8. A documentação indica que não se deve enviar dataset com file_id.
radius=0 restringe a pesquisa à localização do projeto?
Não. Seleciona as estações mais próximas independentemente da distância. Inspecione a distância devolvida antes de aprovar o registo meteorológico.
O que acontece quando a pesquisa não encontra dados para um conjunto de dados?
Solar Dataset Query V2 documenta uma saída null para esse conjunto de dados e um aviso. Exija que a aplicação o conserve e comunique.
Os valores horários de CA são apresentados como energia?
PVWatts V8 documenta ac horário em Wac. O valor mensal ac_monthly e o valor anual ac_annual estão documentados em kWhac.
O que devem verificar os testes de aceitação com parâmetros inválidos?
Ambos os documentos descrevem HTTP 422 para parâmetros inválidos ou ausentes. Verifique se a aplicação lê a secção de erros e comunica a falha.
Sobre o Autor

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.
Citar este artigo
Cinn Song. (2026). Aquisição de API fotovoltaica: especifique JSON ou XML para ambos os endpoints. SOLARTODO. Retrieved from https://solartodo.com/pt/knowledge/should-the-pv-software-integration-specify-json-or-xml-for-both-climate-data-discovery-and-production-calculations
@article{solartodo_should_the_pv_software_integration_specify_json_or_xml_for_both_climate_data_discovery_and_production_calculations,
title = {Aquisição de API fotovoltaica: especifique JSON ou XML para ambos os endpoints},
author = {Cinn Song},
journal = {SOLARTODO Knowledge Base},
year = {2026},
url = {https://solartodo.com/pt/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/pt/knowledge/should-the-pv-software-integration-specify-json-or-xml-for-both-climate-data-discovery-and-production-calculations
Inscreva-se em Nossa Newsletter
Receba as últimas notícias e insights sobre energia solar diretamente em sua caixa de entrada.
Ver Todos os Artigos