> ## Documentation Index
> Fetch the complete documentation index at: https://docs.climatifai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get started with Climatifai API

> Make your first Climatifai API calls in four steps: verify the API, score a crop's aptitude, fetch fire hotspots, and explore the GraphQL playground.

You can start using the Climatifai API without registering or sending any authentication headers. Most endpoints are publicly accessible — just point your requests at your API host. The examples below use `https://your-api-host` as a placeholder; replace it with the base URL of your deployment.

<Steps>
  <Step title="Check the API is running">
    Send a GET request to `/health` to confirm the service is up.

    ```bash theme={null}
    curl https://api.climatifai.com/health
    ```

    A healthy instance returns:

    ```json theme={null}
    {"status": "ok"}
    ```

    If you receive a connection error, verify that the host and port are correct and that the service has started.
  </Step>

  <Step title="Get a crop aptitude score">
    The `/agri/advisor` endpoint scores how well a specific crop fits the climate at a given location. Pass a latitude, longitude, crop ID, and season.

    ```bash theme={null}
    curl "https://api.climatifai.com/agri/advisor?lat=-34.6&lon=-58.4&crop_id=maiz&season=annual"
    ```

    The response includes a 0–100 score, an aptitude label, a per-factor breakdown, and a recommendation in Spanish:

    ```json theme={null}
    {
      "crop_id": "maiz",
      "crop_name": "Maíz",
      "score": 72,
      "aptitude": "Alta",
      "factors": [
        {
          "name": "Precipitación anual",
          "value": 612.4,
          "unit": "mm/año",
          "score": 88,
          "weight": 0.20,
          "status": "ok",
          "ideal": "500–800 mm"
        }
      ],
      "recommendation_text": "La zona tiene condiciones climáticas favorables para el cultivo de Maíz.",
      "_cache": null
    }
    ```

    **Supported `crop_id` values:** `maiz`, `trigo`, `cafe`, `soya`, `vid`, `frijol`, `papa`, `arroz`, `cana`, `tomate`, `cebolla`, `ajo`, `girasol`, `sorgo`, `algodon`, `quinua`, `aguacate`. English aliases such as `maize`, `wheat`, and `coffee` are also accepted.

    **Supported `season` values:** `annual`, `lluvias` (wet season), `secas` (dry season).
  </Step>

  <Step title="Get fire hotspots near a location">
    The `/fires/hotspots` endpoint returns active fire detections from NASA FIRMS VIIRS within a radius around your coordinates. The lookback window is 1–5 days.

    ```bash theme={null}
    curl "https://api.climatifai.com/fires/hotspots?lat=-34.6&lon=-58.4&radius_km=100&days=5"
    ```

    The response lists each detected hotspot with its coordinates, fire radiative power (FRP), acquisition time, satellite, and confidence level:

    ```json theme={null}
    {
      "lat": -34.6,
      "lon": -58.4,
      "radius_km": 100.0,
      "days": 5,
      "count": 3,
      "hotspots": [
        {
          "latitude": -34.21,
          "longitude": -58.11,
          "bright_ti4": 312.4,
          "frp": 8.2,
          "acq_date": "2026-05-16",
          "acq_time": "0148",
          "satellite": "N",
          "confidence": "nominal",
          "source_name": "VIIRS_SNPP_NRT"
        }
      ],
      "_cache": null
    }
    ```

    The `source` parameter defaults to `VIIRS_SNPP_NRT`. The server supplies the NASA FIRMS API key — you do not need one.
  </Step>

  <Step title="Try the GraphQL playground">
    The API includes a fully interactive GraphiQL playground at `/graphql`. Open it in your browser to explore all available queries, including `advisor`, `climate`, `hotspots`, `fireRisk`, `alerts`, `compare`, and more.

    ```text theme={null}
    https://api.climatifai.com/graphql
    ```

    Here is a sample query to score a crop and check fire risk in one request:

    ```graphql theme={null}
    query {
      advisor(lat: -34.6, lon: -58.4, cropId: "maiz", season: "annual") {
        score
        aptitude
        recommendationText
      }
      fireRisk(lat: -34.6, lon: -58.4, radiusKm: 100) {
        riskScore
        riskLabel
        hotspotCount
      }
    }
    ```

    The playground provides schema documentation in the sidebar and autocomplete as you type.
  </Step>
</Steps>