API de exportação de métricas

A API de exportação de métricas fornece qualquer métrica das suas centrais como série temporal, em CSV ou JSON, com um único pedido GET. Lê a mesma coleção de métricas que os relatórios, incluindo as métricas que a sua organização definiu.

Cada ligação que a página Exportação de dados mostra é uma chamada desta API, pelo que a forma mais fácil de chegar a um pedido que funciona é construí-lo aí e copiá-lo.

As ligações de exportação da exportação anterior continuam a funcionar sem alterações. Estão descritas na API de exportação legada; como passar de uma para a outra está no guia de migração.

Rotas

Todos os caminhos são relativos a https://service.mirox.io/api.

Autenticação

Envie um token de API do grupo Metric Export no cabeçalho Authorization:

Authorization: Bearer YOUR_API_TOKEN

O token lê todas as rotas de exportação desta página e as rotas legadas. Não pode criar, alterar nem eliminar nada. Num navegador em que tenha sessão iniciada no Mirox, as ligações funcionam sem token.

Só recebe dados das centrais cujas medições pode ler. As métricas da sua organização são exportadas por todas as funções de organização, exceto Externo. Consulte Quem pode exportar o quê.

Exportar uma série temporal

GET /v1/export/series

Injeção na rede de uma central ao longo do mês anterior, por dia:

curl --compressed "https://service.mirox.io/api/v1/export/series?park=ABC123DEF456&metrics=plant.grid_feedin&window=previous_month&step=day" \
  -H "Authorization: Bearer YOUR_API_TOKEN" -o feedin.csv

Date;Grid feed-in (kWh)
2026-08-01;5321,4
2026-08-02;4980,2
...

Parâmetros

lane_limit e lane_page fora dos seus limites são ajustados ao limite mais próximo. Um parâmetro que a rota não conhece é ignorado.

Métricas e valores

Um ID de métrica tem a forma <prefixo>.<nome>, por exemplo plant.grid_feedin, inverter.ac_power ou sensor.irradiance. Uma métrica da sua organização é organization.<id da métrica>. O catálogo lista-as todas.

Cada métrica tem uma grandeza, que decide os modos de valores que oferece:

Um sufixo define o modo de uma métrica e prevalece sobre values:

metrics=plant.grid_feedin:cumulative,plant.grid_power

Um modo que não se aplica a uma métrica nunca é um erro. A métrica é exportada como native, e a nota value_mode_ignored indica-o. delta nunca é aplicado a uma potência.

A mesma métrica em dois modos dá duas colunas. A mesma métrica duas vezes no mesmo modo dá uma.

Período

Indique o período de uma de três formas. Duas formas num mesmo pedido respondem 400 window_conflict.

Período livre. start e end são uma data (2026-07-01) ou uma data com hora (2026-07-01T06:00, 2026-07-01T06:00:00Z, 2026-07-01T06:00:00+02:00). Um valor sem fuso horário é lido no fuso horário das linhas. Um end que é uma data inclui esse dia; um end com hora é o momento em que o período termina. Sem end, o período termina agora. end sozinho, sem start, é recusado.

Calendário. year de 2020 a 2100, quarter de 1 a 4, month de 1 a 12, week de 1 a 53 (semana ISO), day de 1 a 31. day requer month. Sem year, entende-se o ano em curso. day prevalece sobre week, week sobre month, month sobre quarter.

Predefinições. today, yesterday, last_7_days, last_30_days, this_week, previous_week, this_month, previous_month, this_quarter, previous_quarter, this_year, previous_year. As predefinições this_ vão até agora; last_7_days e last_30_days são móveis até agora com passos inferiores a um dia (a mesma hora 7 ou 30 dias antes); a partir de day são os últimos 7 ou 30 dias locais, incluindo hoje. A partir de day, cada janela é alargada a dias inteiros (semanas, meses …) no fuso horário da central, e a resposta devolve a janela efetiva.

Um período começa, no mínimo, em 2020 e abrange no máximo 1827 dias (cinco anos). Um período que entra no futuro termina agora, com a nota end_clamped.

Passos

step=auto escolhe um passo que todas as métricas pedidas servem e que cabe nos limites: 15min até dois dias, 1h até 62 dias, day até três anos, month para além disso. Se esse passo não couber, é tentado o passo mais grosso seguinte, depois os mais finos. A nota step_auto e o cabeçalho X-Mirox-Step indicam o passo que foi escolhido.

Cada métrica oferece os seus próprios passos. O catálogo lista-os como export_steps:

A potência é oferecida apenas a 15 minutos ou mais fino. Uma potência diária ou mensal é uma média que esconde o que aconteceu; a métrica de energia dá o valor que se pretende.

Um passo nunca é alterado em silêncio. Com mismatch=refuse, a predefinição, um passo que uma das métricas não serve responde 400 step_not_served com os passos de cada métrica, e com step=auto as métricas que não partilham nenhum passo respondem 400 no_common_step. Com mismatch=sparse, esse pedido é entregue na mesma — consulte Métricas com passos diferentes.

Os passos de um dia ou mais cobrem intervalos completos. Um período que começa ou termina dentro de um deles é alargado para fora, com a nota window_aligned. As semanas começam à segunda-feira.

Métricas com passos diferentes

mismatch=sparse entrega um pedido cujas métricas não servem todas o passo, desde que cada uma sirva algum passo. A grelha do ficheiro é o passo pedido; com step=auto é o passo que mais métricas servem tal como está, escolhido pelo período e pelos limites como habitualmente. As posições das colunas e a forma da resposta CSV e JSON não mudam.

Dois casos são recusados em ambos os modos, com 400 step_not_served: um valor por mês, trimestre ou ano num ficheiro por week, porque o seu primeiro dia quase nunca é uma segunda-feira; e um valor mensal como o Marktwert num ficheiro por quarter ou year, porque uma soma ou uma média de meses não é esse valor. Num ficheiro por month é lido tal como está; num mais fino fica esparso.

A estimativa lista as mesmas notas, conta as leituras no passo próprio de cada métrica e marca um passo em per_step como dentro do limite mesmo quando nem todas as métricas o servem. A página Exportação de dados pede sempre com mismatch=sparse; um modelo traz o seu próprio mismatch na sua spec.

Grelha temporal

Com tz=local, as linhas seguem a hora local da central, incluindo a hora de verão: um dia é um dia local de 23, 24 ou 25 horas, um mês é um mês local. Com tz=utc, as linhas seguem o calendário UTC.

• Em passos mais curtos do que um dia na hora local, a coluna Desvio UTC segue-se à coluna de tempo (+02:00). No dia em que os relógios atrasam, uma hora aparece duas vezes; o desvio distingue as duas. offset_column=false omite a coluna.
• As centrais em fusos horários diferentes partilham uma só coluna de tempo. Um pedido destes é respondido no calendário UTC, com a nota merged_on_utc, quer as centrais estejam combinadas, quer separadas.
• Com tz=utc e um passo de um dia ou mais, uma métrica que só existe por dia local não tem valor UTC. A sua coluna fica vazia, com a nota utc_calendar_unsupported.

O cabeçalho X-Mirox-Grid indica o calendário que foi usado: local:Europe/Berlin ou utc.

Várias centrais

Com multi_park_agg=merge, cada métrica é uma coluna para todas as centrais, combinada pela regra da métrica. O catálogo lista a regra como merge:

Uma métrica que não pode ser combinada é exportada por central, com a nota merge_not_meaningful. O mesmo vale para um rácio num passo em que as suas duas metades não estão disponíveis, e para preços de centrais em zonas de mercado diferentes.

Com multi_park_agg=split, cada métrica é uma coluna por central. Com uma única central, ambos dão o mesmo ficheiro.

As métricas de componentes são sempre por central (nota components_split_by_park).

Componentes

Uma métrica de um nível de componente dá uma coluna por componente. Os níveis são inverter, gak (caixa de junção), string, turbine, sensor, meter, battery_box (contentor), battery_storage (rack), battery_module, battery_cell e battery_pcs (conversor).

Sem components, a exportação contém todos os componentes visíveis das centrais, lane_limit por métrica e página. Se houver mais, a nota lanes_truncated indica o total; peça a página seguinte com lane_page.

components restringe a exportação aos componentes que indicar. Uma referência tem a forma <nível>:<id>, por exemplo inverter:1043. Um sensor ou contador que o Mirox mede, mas que não tem entrada nos componentes da central, tem uma referência da forma sensor:h3f9c2a71b04e6d5. A rota de componentes lista as referências de uma central. Uma referência que não pertence a nenhuma das centrais selecionadas responde 400 unknown_lane.

metrics=inverter.ac_power&components=inverter:1043,inverter:1044

Consultas MetricsQL em bruto

expr acrescenta a uma exportação uma consulta em bruto em MetricsQL, a linguagem de consulta da base de dados de séries temporais da plataforma — para uma série para a qual a coleção não tem métrica. O parâmetro pode repetir-se até cinco vezes; cada expressão pode ter até 4 000 caracteres. Um pedido pode levar só expr, ou metrics e expr em conjunto; as colunas das métricas vêm primeiro.

expr=sum by (inverter_id) (powerplant_inverter_power_ac)&park=ABC123DEF456&window=yesterday&step=15min

Uma expressão é avaliada por central, como um painel a avalia: sobre os dados da própria central, no passo pedido, como amostras brutas — qualquer passo é permitido, e values e as regras de agregação das métricas não se aplicam. O Mirox acrescenta a central a cada seletor da expressão; uma expressão que nomeia ela própria uma etiqueta park, organization ou plant é recusada com 400 expr_forbidden_label.

Quando uma expressão devolve várias séries em alguma das suas centrais, as colunas dessa expressão em todas as centrais levam as etiquetas das séries, para que um ficheiro tenha uma só nomenclatura por expressão. Um cabeçalho com mais de 1 000 caracteres é cortado com … dentro da expressão, nunca no texto da série. Na resposta JSON, columns[].key é o texto de header=id e columns[].metric é o ID da expressão, expr.e1, expr.e2, …, que as notas e as recusas usam. Uma central em que a expressão não devolve nada mantém uma coluna vazia, com a nota expr_no_series; com várias centrais, cada central recebe as suas próprias colunas, com a nota expr_split_by_park.

Uma expressão pode devolver no máximo 500 séries numa central (400 expr_too_many_series); agregue-a, por exemplo com sum by (…). As séries contam para as mesmas 400 colunas e 1 800 000 valores de qualquer exportação: a primeira leitura de cada expressão em cada central é uma sonda curta, as larguras são somadas em todo o pedido, e um pedido que ultrapassa os limites é recusado com 400 over_budget e params.series antes de qualquer leitura completa de qualquer expressão. Uma expressão que não se consegue analisar, está vazia, é demasiado longa ou que a base de dados recusa responde 400 expr_invalid com o reason.

A estimativa conta uma expressão como uma coluna por central, porque as suas séries só se conhecem depois de lida. As expressões não são guardadas em modelos.

Resposta CSV

A resposta está em UTF-8, com o nome de ficheiro series_export_<primeiro dia>_<último dia>_<passo>.csv. Uma resposta maior do que cerca de 1 MB é comprimida quando o pedido contém Accept-Encoding: gzip (curl: --compressed).

As colunas são, por esta ordem: o tempo, o Desvio UTC quando se aplica, e depois as métricas pela ordem de metrics.

A coluna de tempo é formatada por passo, salvo se datetime_format for indicado:

Cada linha é marcada com o início do seu intervalo. Um valor em falta é uma célula vazia, pelo que «sem dados» e «zero» se distinguem; empty=zero escreve 0 em vez disso.

Quatro cabeçalhos da resposta repetem o que foi resolvido:

Resposta JSON

format=json responde com a mesma tabela em dados estruturados:

Notas

Uma nota diz-lhe o que o Mirox fez por iniciativa própria. Nunca faz falhar uma exportação. As notas fazem parte da resposta JSON e do cabeçalho X-Mirox-Notes. O cabeçalho contém até 1 KB de notas, escritas como code:key=value,key=value e separadas por ;. Se não couberem todas, o cabeçalho termina com notes_omitted:count=<n>; a resposta JSON contém-nas todas.

Uma coluna vazia é sempre mantida. Uma métrica que não se aplica a uma das centrais, ou uma métrica monetária sem a permissão de contabilidade, deixa a sua coluna no lugar, pelo que as posições das outras colunas nunca se alteram.

Estimar antes de exportar

GET /v1/export/series/estimate

A rota aceita os parâmetros da exportação, sem o formato do ficheiro, e responde com o que a exportação seria — sem ler dados e sem contar para o limite horário.

Uma recusa nunca faz falhar a estimativa: responde 200 e lista a recusa. A estimativa conta, não gera nada: os rótulos das linhas e os cabeçalhos são os da exportação. Uma consulta em bruto conta como uma coluna por central, e com mismatch=sparse as notas indicam as colunas agregadas e esparsas.

O catálogo de métricas

GET /v1/export/series/catalog

Cada métrica tem, além do seu ID, nome, descrição, unidade e nível:

Até 10 centrais, cada central é verificada quanto ao equipamento de que uma métrica precisa. Acima disso, as centrais são avaliadas apenas pelo seu tipo; o que falta a uma central em particular aparece no momento da exportação como nota metric_unavailable.

Glossário. format=csv responde com a lista filtrada inteira num ficheiro, metric_catalog_<language>.csv, com as colunas ID, nível, nome, unidade, descrição, grandeza, modos de valores, passos, intervalo de medição, combinação entre centrais, nota e IDs anteriores. page e limit não se aplicam.

curl "https://service.mirox.io/api/v1/export/series/catalog?format=csv&language=en" \
  -H "Authorization: Bearer YOUR_API_TOKEN" -o metric_catalog_en.csv

Métricas disponíveis

A coleção está ordenada por nível. O prefixo de um ID diz onde uma métrica pertence.

A lista completa com nomes, unidades e descrições no seu idioma é o catálogo, o ficheiro de glossário, ou Explicações no separador Métricas. Os valores de previsão meteorológica da exportação anterior não fazem parte da coleção; consulte o guia de migração.

Componentes de uma central

GET /v1/export/series/lanes

Cada entrada tem a referência ref para o parâmetro components, o name, o level, o elemento superior (parent_ref, parent_name — o inversor de uma string, por exemplo), attributes (role de um contador, position de um sensor de irradiância, vendor), hidden, e source: db para uma entrada dos componentes da central, store para uma série que é medida mas não tem essa entrada.

Uma central que não existe e uma central que não pode ler respondem ambas 404 park_not_found.

Sistema de modelos

Um modelo é uma lista guardada de métricas com predefinições para passo, período, valores, fuso horário, combinação de centrais, tamanho da página de componentes e cabeçalhos das colunas. Para que servem os modelos e como geri-los na aplicação está no guia da exportação de métricas.

Exportar um modelo

GET /v1/export/series/template/{template_uid}

A rota aceita os parâmetros da exportação, exceto metrics, components e values, que o modelo fixa. Cada parâmetro que omitir assume a predefinição do modelo; cada parâmetro que indicar prevalece sobre ela.

curl --compressed "https://service.mirox.io/api/v1/export/series/template/CAFE1000CAFE?park=ABC123DEF456&window=previous_month&header=id" \
  -H "Authorization: Bearer YOUR_API_TOKEN" -o standard.csv

• Um modelo de outra organização responde 404 template_not_found.
• Um modelo legado responde 400 template_is_legacy; params.legacy_url é a ligação que o exporta.
• Uma coluna cuja métrica já não está disponível é exportada vazia sob o seu cabeçalho, com a nota metric_unavailable. O mesmo se aplica a uma métrica da sua organização quando exporta como Externo (reason not_permitted).

Modelos do sistema

Os primeiros cinco sucedem a CAFE0000CAFE, CAFE0001CAFE, CAFE0002CAFE, CAFE0003CAFE e ABCD12340001, que continuam a funcionar na rota legada. As suas colunas estão listadas no guia de migração. Oferecem os passos day, week, month, quarter e year; os quatro primeiros oferecem também 15min e 1h.

Gerir modelos

Os modelos são listados, lidos, criados, alterados e eliminados em /v1/export/template. A leitura funciona com um token Metric Export. A escrita requer a função de organização Administrador, Moderador, Gestor de ativos (técnico) ou Gestor de ativos (comercial) e uma sessão iniciada ou um token Acesso total.

O spec de um modelo:

label é o texto de cabeçalho da coluna com header=name. Uma métrica só pode aparecer uma vez, e um modelo não contém consultas em bruto. Quando um modelo é guardado, todas as métricas têm de ser exportáveis, e as métricas têm de partilhar um passo — com mismatch=sparse, cada uma tem de servir algum passo; caso contrário, a resposta é 422 spec_invalid e params.problems indica a métrica e o motivo. Um modelo corre com o seu próprio mismatch (a aplicação mostra-o como Métricas de outro passo: Estrito ou Flexível); o parâmetro na ligação de exportação prevalece.

Converter um modelo legado

POST /v1/export/template/{template_uid}/convert

A resposta lista mapped (legacy_id, metric, values, exactness: exact ou approximate) e unmapped (legacy_id, reason: formula, no_equivalent, report_value ou instant, e até três suggestions), e, salvo se tiver sido um ensaio, o novo template. Um ensaio responde 200, uma conversão 201.

O novo modelo exporta dias ao longo do mês anterior. O modelo legado nunca é alterado. Duas colunas legadas que leem o mesmo contador tornam-se uma só coluna. 422 nothing_to_convert significa que nenhuma coluna tem equivalente, ou que o modelo não é um modelo legado.

Limites

Uma exportação é respondida dentro de um único pedido, pelo que o seu tamanho é limitado. Cada limite é verificado antes de os dados serem lidos; um pedido demasiado grande é recusado de imediato e diz-lhe o que caberia.

Dividir uma exportação grande

400 over_budget indica em params o que era necessário e o que é permitido, e em hint a saída: step, o passo mais grosso seguinte que cabe, e max_days, o período mais longo que cabe no passo pedido. Se construir pedidos num script, consulte primeiro a estimativa; o seu per_step lista o tamanho para cada passo.

Se não quiser nem um passo mais grosso nem um período mais curto, divida a exportação:

Algumas métricas são apuradas a partir de várias fontes para cada dia, sobretudo plant.production_reported (Produção, resolvida). Precisam de muito mais leituras do armazenamento de medições do que uma leitura de contador, em todos os passos. Um pedido ou um modelo que contém uma métrica destas abrange atualmente cerca de nove meses-central: uma central ao longo de nove meses, ou nove centrais ao longo de um mês. Um passo de uma semana ou mais alarga o período a intervalos completos, e é o período alargado que conta. Divida essas exportações por tempo ou por central, ou exporte a métrica num pedido próprio.

429 busy e 429 rate_limited têm o cabeçalho Retry-After com os segundos a aguardar.

Erros

Um erro das rotas desta página tem esta forma:

{
  "detail": {
    "code": "step_not_served",
    "message": "The step is not served by every requested metric.",
    "params": {"step": "1h", "metrics": {"plant.grid_power": ["1min", "5min", "15min"]}},
    "hint": {"offered_common": ["1min", "5min", "15min"]}
  }
}

code é estável e destina-se a programas. message é um texto em inglês para pessoas. params diz o que estava errado, hint o que funcionaria.

401 significa que o token está em falta, expirou ou foi revogado.

IDs da exportação anterior

O parâmetro metrics também aceita os IDs da exportação anterior, como energy_grid_daily ou raw_grid_power. Um ID com equivalente é traduzido para a sua métrica, no modo de valores que mais se aproxima do número anterior, e a nota legacy_id_mapped diz que métrica respondeu e se o número é o mesmo (exact) ou a mesma grandeza lida de uma forma melhor (approximate).

Um ID sem equivalente responde 400 legacy_metric_id. hint.reason diz porquê, hint.closest indica a métrica mais próxima quando existe, hint.pending indica a métrica que está previsto vir a fornecê-lo, e legacy_url é a ligação da exportação anterior que continua a fornecer o ID. Com mais centrais do que uma ligação pode indicar, legacy_url indica a primeira central e params.legacy_url_scope é first. Um ID de componente de um nível de bateria não tem ligação da exportação anterior; hint.legacy_route é então none. O guia de migração lista todos os IDs.

Excel e scripts

• Exportação de métricas para Excel — receitas, e a ligação Power Query com o cabeçalho Authorization
• Gerador de relatórios externo — um exemplo completo em Python

Funcionalidades relacionadas

• Exportação de métricas — a página Exportação de dados
• Migrar para a exportação de métricas — IDs antigos, novas métricas e o que muda
• API de exportação legada — as ligações de exportação anteriores
• Métricas — definir métricas próprias e exportá-las
• Tokens de API — criar o token Metric Export
• Visão geral da API — a referência interativa de todas as rotas