Perguntas
Frequentes
Encontre respostas para suas dúvidas
Callback de Uso do Solo (LandUse)
SUMÁRIO​
-
Exemplos de Retorno e Formato JSON
​
1- Visão Geral
O Callback de Uso do Solo entrega informações detalhadas sobre a cobertura e uso da terra dentro dos talhões ou glebas analisadas. Essas informações são organizadas por safra (identificadas pelo seasonCode). Este Callback se aplica para relatórios de Monitoramento.
​
Exemplo de API:
-
Endpoint: /insurance/report/callback/land-uses
-
Swagger (produção): Produção
-
Swagger (validação): Validação
​​
Tipo de Envio:
Os dados são enviados integralmente, ou seja, todos os dados são retornados de uma vez, e não de forma fragmentada.
​
Fontes de Classificação Esperadas (landUses):
​
-
MAPBIOMAS_LAND_USE: Fonte de dados do Mapbiomas
-
CYAN_LAND_USE: Classificação do uso de solo realizada pelo classificador automático da Cyan
2 - Estrutura do Payload
O Payload contém as informações detalhadas sobre o relatório de uso do solo, incluindo identificadores e os dados de uso agrupados por safra.
Campos do Objeto Principal
reportRequestId
​
-
TIPO:
-
Integer
-
-
DESCRIPTION:
-
Identificador da solicitação original de processamento.
-
reportId
​
-
TIPO:
-
Integer
-
-
DESCRIPTION:
-
Identificador único do relatório.
-
createdAt
​
-
TIPO:
-
String
-
-
DESCRIPTION:
-
Data e hora em que o resultado foi gerado/salvo (Formato: YYYY-MM-DD hh:mm:ss).
-
colorLegendImageFileUrl
​
-
TIPO:
-
String
-
-
DESCRIPTION:
-
URL do arquivo da legenda de cores usada nos mapas de uso do solo gerados.
-
landUses
​
-
TIPO:
-
Array de Objetos
-
-
DESCRIPTION:
-
Lista de usos do solo, agrupados por safra (seasonCode).
-
Estrutura de LandUses (Agrupamento por Safra)
seasonCode
​
-
TIPO:
-
String
-
-
DESCRIPTION:
-
Código ou ano da safra (ex: "2023", "2024").
-
products
​
-
TIPO:
-
Array de Objetos
-
-
DESCRIPTION:
-
Lista dos diferentes tipos de uso do solo (code) encontrados naquela safra.
-
Cada objeto dentro de landUses corresponde a uma safra, incluindo os produtos e suas classificações.
Estrutura de products (Detalhes do Uso do Solo):
Cada objeto dentro da lista products detalha o tipo de uso/cobertura do solo encontrado na safra.
percentage
​
-
TIPO:
-
Double
-
-
Código que identifica o tipo de uso do solo (Ex: "20" para Pastagem, "55" para Soja, etc.):
-
Percentual da área total do talhão/gleba ocupado por este produto.
-
area
​
-
TIPO:
-
Double
-
-
Código que identifica o tipo de uso do solo (Ex: "20" para Pastagem, "55" para Soja, etc.):
-
Área em hectares ocupada por este produto.
-
geometryFileUrl
​
-
TIPO:
-
String
-
-
Código que identifica o tipo de uso do solo (Ex: "20" para Pastagem, "55" para Soja, etc.):
-
URL para o arquivo GeoJSON que representa a geometria desta área de uso do solo.
-
imageFileUrl
​
-
TIPO:
-
String
-
-
Código que identifica o tipo de uso do solo (Ex: "20" para Pastagem, "55" para Soja, etc.):
-
URL para o arquivo de imagem (JPEG/PNG) representando a visualização deste uso do solo no mapa.
-
3 - Regra de Atualização e Conteúdo Vazio
Regra de Atualização:
​
A identificação de um registro existente é feita pela combinação de:
-
reportId
-
seasonCode
-
product code
Caso um seasonCode e product code para um determinado reportId já estejam salvos, os dados relacionados a essa safra serão atualizados com os novos valores.
​
Conteúdo Vazio:
Se a análise de uso do solo não encontrar dados para o relatório, o campo landUses será retornado como uma lista vazia, ou seja, [].
​
Exemplo de Retorno com Lista Vazia:
{
"reportRequestId": 12345,
"reportId": 100,
"createdAt": "2024-06-13 13:00:00",
"landUses": []
}
4 - Detalhes sobre a Classificação do Uso do Solo
A classificação do uso do solo é feita com base em uma combinação de dados do Mapbiomas e do classificador automático (CYAN_LAND_USE). A regra de classificação funciona da seguinte maneira:
​
-
Para culturas de milho e soja:
-
-
A classificação dos primeiros anos da safra (primeiro ou segundo ano, dependendo da disponibilidade dos dados do Mapbiomas) será realizada utilizando o Mapbiomas.
-
A última safra (e, quando aplicável, a penúltima) será classificada utilizando o classificador automático.
-
-
Para outras culturas (que não sejam milho ou soja):
-
-
A classificação de todas as safras será feita exclusivamente pelo classificador automático, independentemente da disponibilidade de dados do Mapbiomas.
-
Importante: Apesar de utilizarmos fontes e metodologias diferentes para a classificação (Mapbiomas e classificador automático), todos os dados serão disponibilizados para o TI por meio de um único callback de CYAN_LAND_USE.
5 - Exemplos de Retorno e Formato JSON
Exemplo de Retorno Completo (com Dados de Uso do Solo):
{
"reportRequestId": 12345,
"reportId": 100,
"createdAt": "2024-06-13 13:00:00",
"colorLegendImageFileUrl": "https://example.com/legend.png",
"landUses": [
{
"seasonCode": "2023",
"products": [
{
"code": "55",
"percentage": 50.5,
"area": 200.0,
"geometryFileUrl": "https://example.com/geometry.geojson",
"imageFileUrl": "https://example.com/map.png"
},
{
"code": "20",
"percentage": 30.0,
"area": 120.0,
"geometryFileUrl": "https://example.com/geometry.geojson",
"imageFileUrl": "https://example.com/map.png"
}
]
},
{
"seasonCode": "2024",
"products": [
{
"code": "55",
"percentage": 60.0,
"area": 250.0,
"geometryFileUrl": "https://example.com/geometry.geojson",
"imageFileUrl": "https://example.com/map.png"
}
]
}
]
}