REST API · Core v1

API Reference

Endpoints reais do backend Core em produção. Todos os layers recebem um código CAR e retornam dados geoespaciais processados — vegetação, solo, clima, compliance, logística, ZARC e muito mais.

REST · JSONFastAPI + Pydantic

Cache 90 diasRedis por geo-query

GEE + SICARGoogle Earth Engine

CAR obrigatórioUF-IBGE7-HASH32

Sistema

GEThttps://core-qfho.onrender.com/v1/health

Health Check

Verifica a saúde dos serviços internos: PostgreSQL, Redis e Google Earth Engine (GEE). Retorna status geral e por serviço.

200 OK · Response

/health

{
  "status": "healthy",
  "services": {
    "postgres": "up",
    "redis":    "up",
    "gee":      "up"
  }
}

Propriedade

GEThttps://core-qfho.onrender.com/v1/car/{car_code}

Dados da Propriedade (CAR)

Busca os dados da propriedade rural via SICAR pelo código CAR. Retorna geometria, área, município, estado e condição de análise.

ℹPadrão: ^[A-Z]{2}-\d{7}-[A-Fa-f0-9]{32}$

Parâmetros

car_codepath · stringobrigatório

Código CAR no formato UF-IBGE7-HASH32. Ex.: ES-3202207-AABA8DD8038F4BF681C40F44A98163F1

200 OK · Response

/car/{car_code}

{
  "car_code": "ES-3202207-AABA8DD8038F4BF681C40F44A98163F1",
  "status": "AT",
  "city": "Sorriso",
  "state": "MT",
  "total_area_ha": 432.7,
  "fiscal_modules": 7,
  "registered_at": "2018-03-14",
  "analysis_condition": "Regular",
  "centroid": { "latitude": -12.548, "longitude": -55.712 },
  "geometry_polygon": [[-55.73, -12.535], ...]
}

Layers

GEThttps://core-qfho.onrender.com/v1/layers/vegetation

Vegetação (NDVI / EVI)

Análise de saúde da vegetação via Google Earth Engine. Retorna NDVI, EVI, tendência temporal, risco de fogo e classe de umidade. Cache de 90 dias no Redis.

Parâmetros

carquery · stringobrigatório

Código CAR da propriedade.

200 OK · Response

/layers/vegetation

{
  "data": {
    "ndvi": {
      "current": 0.72,
      "mean": 0.68,
      "trend_slope": 0.003,
      "trend_class": "recovering",
      "timeseries": [
        { "year": 2022, "value": 0.65 },
        { "year": 2023, "value": 0.70 },
        { "year": 2024, "value": 0.72 }
      ]
    },
    "evi": { "current": 0.61, "mean": 0.57 },
    "ndvi_class": "high",
    "moisture_class": "moderate",
    "fire_risk_class": "low"
  }
}

GEThttps://core-qfho.onrender.com/v1/layers/soil

Solo

Dados pedológicos via SoilGrids. Textura (argila, areia, silte), carbono orgânico de superfície, pH e classificação de fertilidade.

Parâmetros

carquery · stringobrigatório

Código CAR da propriedade.

200 OK · Response

/layers/soil

{
  "data": {
    "organic_carbon": { "surface_g_per_kg": 18.4, "class": "moderate" },
    "texture": { "clay_pct": 42, "sand_pct": 35, "silt_pct": 23, "class": "clayey" },
    "ph": { "surface": 5.8, "class": "acidic" },
    "summary": "Solo argiloso com carbono orgânico moderado..."
  }
}

GEThttps://core-qfho.onrender.com/v1/layers/agroclimate

Agroclima

Precipitação anual, déficit hídrico, balanço hídrico, eventos extremos (Z-score), risco de inundação e proximidade a corpos d'água via ERA5/GEE.

Parâmetros

carquery · stringobrigatório

Código CAR da propriedade.

200 OK · Response

/layers/agroclimate

{
  "data": {
    "precipitation": {
      "mean_annual_mm": 1820,
      "latest_year_mm": 1755,
      "timeseries": [{ "year": 2023, "total_mm": 1755 }]
    },
    "water_deficit": { "avg_deficit_months": 2.3, "class": "low" },
    "water_balance": { "mean_annual_mm": 420, "class": "surplus" },
    "extreme_events": { "count": 1 },
    "flood_risk": { "flood_area_pct": 1.2, "class": "low" }
  }
}

GEThttps://core-qfho.onrender.com/v1/layers/environmental_compliance

Compliance Ambiental

Status do CAR, APP e Reserva Legal, embargos IBAMA/ICMBio, sobreposições com UCs e terras indígenas, e alertas de desmatamento via PRODES/DETER.

Parâmetros

carquery · stringobrigatório

Código CAR da propriedade.

200 OK · Response

/layers/environmental_compliance

{
  "data": {
    "car_status": "AT",
    "app": { "total_area_ha": 24.3, "status": "compliant" },
    "legal_reserve": { "total_area_ha": 86.5, "status": "compliant" },
    "embargoes": { "ibama": { "active_count": 0 }, "icmbio": { "active_count": 0 } },
    "overlaps": {
      "conservation_units": { "count": 0 },
      "indigenous_lands": { "count": 0 }
    },
    "deforestation": { "net_deforestation_ha": 0, "alerts_count": 0 },
    "risk_class": "compliant"
  }
}

GEThttps://core-qfho.onrender.com/v1/layers/land_use

Uso do Solo

Classificação anual MapBiomas: área agrícola vs. nativa, cultura dominante, classe de conversão e desmatamento líquido.

Parâmetros

carquery · stringobrigatório

Código CAR da propriedade.

200 OK · Response

/layers/land_use

{
  "data": {
    "current_year": 2024,
    "agro_pct": 78.4,
    "native_pct": 21.6,
    "conversion_class": "stable",
    "net_deforestation_ha": 0,
    "dominant_crop": {
      "crop_key": "soybean",
      "label": "Soja",
      "area_ha": 289.3,
      "confidence_score": 0.91
    },
    "risk_class": "low"
  }
}

GEThttps://core-qfho.onrender.com/v1/layers/temperature

Temperatura

Classe térmica, risco de geada, stress térmico, GDD acumulado e culturas indicativas para o clima da propriedade via ERA5.

Parâmetros

carquery · stringobrigatório

Código CAR da propriedade.

200 OK · Response

/layers/temperature

{
  "data": {
    "thermal_class": "tropicalWarm",
    "frost_risk_class": "none",
    "heat_stress_class": "low",
    "mean_annual_c": 25.8,
    "mean_min_c": 18.2,
    "mean_max_c": 33.1,
    "mean_annual_gdd": 3820,
    "apt_crops_indicative": ["soybean", "corn", "cotton"]
  }
}

GEThttps://core-qfho.onrender.com/v1/layers/topography

Topografia

Modelo digital de elevação (SRTM/Copernicus), declividade média, classe de mecanizabilidade e risco de erosão.

Parâmetros

carquery · stringobrigatório

Código CAR da propriedade.

200 OK · Response

/layers/topography

{
  "data": {
    "relief_class": "gentleUndulating",
    "mechanization_class": "full",
    "erosion_risk_class": "low",
    "pct_fully_mechanizable": 94,
    "slope_mean_pct": 3.2,
    "elevation_mean_m": 362
  }
}

GEThttps://core-qfho.onrender.com/v1/layers/zarc

ZARC — Zoneamento Agrícola

Zoneamento Agrícola de Risco Climático (ZARC/MAPA). Geocódigo IBGE extraído direto do CAR. Inclui janelas de semeadura, aptidão por cultura/ciclo/solo, elegibilidade Proagro e ranking de culturas para o município.

ℹNão requer resolução de geometria via SICAR — usa UF-IBGE7 do próprio código CAR.

Parâmetros

carquery · stringobrigatório

Código CAR da propriedade.

200 OK · Response

/layers/zarc

{
  "data": {
    "top_annual_culture": {
      "culture": "Soja",
      "management": "Sequeiro",
      "aptitude_score": 3,
      "aptitude_label": "Alta aptidão",
      "planting_window": "01/10 – 31/12"
    },
    "top_perennial_culture": {
      "culture": "Café Arábica",
      "aptitude_score": 2
    },
    "is_planting_season": true,
    "proagro_eligible": true,
    "annual_cultures_count": 12
  }
}

GEThttps://core-qfho.onrender.com/v1/layers/phytosanitary

Fitossanidade

Pressão de pragas e doenças, proximidade a corredores fitopatológicos e classificação de risco fitossanitário para a região da propriedade.

Parâmetros

carquery · stringobrigatório

Código CAR da propriedade.

200 OK · Response

/layers/phytosanitary

{
  "data": {
    "pest_pressure_index": 2.1,
    "nearest_pest_corridor_km": 84,
    "primary_risks": ["ferrugem_asiatica", "mosca_branca"],
    "risk_class": "moderate"
  }
}

GEThttps://core-qfho.onrender.com/v1/layers/phenology

Fenologia

Fase de desenvolvimento da cultura identificada via assinatura espectral (Sentinel-2/GEE): vegetativa, florescimento ou maturação.

Parâmetros

carquery · stringobrigatório

Código CAR da propriedade.

200 OK · Response

/layers/phenology

{
  "data": {
    "dominant_crop": "soybean",
    "phenological_stage": "vegetative",
    "stage_start_approx": "2024-10-15",
    "estimated_harvest": "2025-02-10",
    "confidence": 0.87
  }
}

GEThttps://core-qfho.onrender.com/v1/layers/land_tenure

Regularidade Fundiária

Cruzamento SIGEF/SNCI, situação de posse, sobreposições de matrículas e consistência entre área registrada e área satélite.

Parâmetros

carquery · stringobrigatório

Código CAR da propriedade.

200 OK · Response

/layers/land_tenure

{
  "data": {
    "sigef_match": true,
    "registered_area_ha": 432.7,
    "satellite_area_ha": 430.1,
    "overlap_claims": 0,
    "registry_status": "clear"
  }
}

GEThttps://core-qfho.onrender.com/v1/layers/logistics

Logística

Distância ao terminal graneleiro mais próximo, condições de acesso viário, sazonalidade de estradas e benchmark de frete regional.

Parâmetros

carquery · stringobrigatório

Código CAR da propriedade.

200 OK · Response

/layers/logistics

{
  "data": {
    "nearest_terminal_km": 28,
    "nearest_terminal_name": "Terminal Graneleiro Sorriso",
    "paved_road_km": 4.2,
    "road_condition": "good",
    "freight_brl_t": 68,
    "logistics_score": 8.3
  }
}

GEThttps://core-qfho.onrender.com/v1/layers/energy_access

Acesso à Energia

Eletrificação rural da propriedade — presença de rede elétrica, proximidade a subestações e classificação de infraestrutura energética.

Parâmetros

carquery · stringobrigatório

Código CAR da propriedade.

200 OK · Response

/layers/energy_access

{
  "data": {
    "has_electricity": true,
    "nearest_substation_km": 8.4,
    "energy_infra_class": "adequate"
  }
}

GEThttps://core-qfho.onrender.com/v1/layers/productive_performance

Desempenho Produtivo

Produtividade histórica estimada via integração de sinal espectral, correlacionada com benchmarks municipais CONAB. Inclui volatilidade interanual.

Parâmetros

carquery · stringobrigatório

Código CAR da propriedade.

200 OK · Response

/layers/productive_performance

{
  "data": {
    "dominant_crop": "soybean",
    "avg_yield_t_ha": 3.4,
    "trend": "above_regional",
    "coefficient_of_variation": 0.12,
    "volatility_class": "low",
    "seasons": [
      { "year": "2023/24", "yield_t_ha": 3.6, "vs_regional_pct": 116 },
      { "year": "2022/23", "yield_t_ha": 3.4, "vs_regional_pct": 110 }
    ]
  }
}

GEThttps://core-qfho.onrender.com/v1/layers/coherence

Coerência (Multi-layer)

Cross-valida dados declarados vs. satélite em múltiplos eixos: uso do solo, compliance ambiental, regularidade fundiária, ZARC e (opcional) cultura declarada para crédito.

ℹEixo 5 ativo apenas com `crop`. Valores aceitos: coffee, soybean, corn, sugarcane, beans, rice, cotton.

Parâmetros

carquery · stringobrigatório

Código CAR da propriedade.

cropquery · stringopcional

Cultura declarada para crédito (Proagro/PSR/custeio). Habilita o Eixo 5.

200 OK · Response

/layers/coherence

{
  "data": {
    "overall_result": "MATCH",
    "axes": {
      "land_use":     { "result": "match",    "score": 95 },
      "compliance":   { "result": "compliant","score": 100 },
      "land_tenure":  { "result": "clear",    "score": 98 },
      "zarc":         { "result": "eligible", "score": 90 },
      "crop_match":   { "result": "exact",    "score": 91 }
    },
    "flags": [],
    "declared_crop": "soybean",
    "observed_crop": "soybean",
    "confidence": 0.91
  }
}

Pronto para integrar?

Acesse a plataforma

Use o código CAR de qualquer propriedade e gere relatórios completos em segundos.

Abrir plataforma