IsItWater

Determine whether a latitude/longitude coordinate is over water using the IsItWater API.

Setup

Before making API calls, check whether the user has an API key configured:

1. Check if ISITWATER_API_KEY is set in the environment.
2. If it is not set:
   • Inform the user: "You need an IsItWater API key. You can get one at https://isitwater.com"
   • Offer to help them sign up using the browser tool — navigate to https://isitwater.com, create an account, and generate an API key from the dashboard.
   • Once the user has a key, guide them to configure it in ~/.openclaw/openclaw.json:

{
  "skills": {
    "entries": {
      "isitwater": {
        "apiKey": "YOUR_API_KEY_HERE"
      }
    }
  }
}

• Alternatively, the user can export the environment variable directly: export ISITWATER_API_KEY=YOUR_API_KEY_HERE

3. Once the key is available, proceed with the API calls below.

Water Lookup

Check whether a coordinate is over water or land.

Endpoint: GET https://api.isitwater.com/v1/locations/water

Headers:

• Authorization: Bearer $ISITWATER_API_KEY

Query Parameters:

| Parameter | Type | Required | Description | |-----------|--------|----------|--------------------------------| | lat | number | yes | Latitude, between -90 and 90 | | lon | number | yes | Longitude, between -180 and 180 |

Example curl:

curl -s "https://api.isitwater.com/v1/locations/water?lat=41.7658&lon=-72.6734" \
  -H "Authorization: Bearer $ISITWATER_API_KEY"

Example response (land):

{
  "request_id": "abc123",
  "water": false,
  "features": ["earth"],
  "latitude": "41.7658",
  "longitude": "-72.6734"
}

Example response (water):

{
  "request_id": "def456",
  "water": true,
  "features": ["earth", "ocean"],
  "latitude": "36.0",
  "longitude": "-30.0"
}

Response Fields:

| Field | Type | Description | |--------------|----------|-----------------------------------------------------------------------------------------------------| | request_id | string | Unique identifier for the request | | water | boolean | true if the coordinate is over water, false if over land | | features | string[] | Geographic features at the point — e.g. earth, ocean, lake, river, glacier, nature_reserve | | latitude | string | The latitude that was queried | | longitude | string | The longitude that was queried |

Cost: 1 credit per lookup.

Account Info

Check the user's account details and remaining credit balance.

Endpoint: GET https://api.isitwater.com/v1/accounts/me

Headers:

• Authorization: Bearer $ISITWATER_API_KEY

Example curl:

curl -s "https://api.isitwater.com/v1/accounts/me" \
  -H "Authorization: Bearer $ISITWATER_API_KEY"

Response Fields:

| Field | Type | Description | |------------------------|---------|--------------------------------------| | id | string | Account identifier | | name | string | Account name | | balance | number | Remaining credits | | auto_recharge_enabled| boolean | Whether auto-recharge is turned on |

Cost: Free (no credits consumed).

Error Handling

| Status Code | Meaning | Description | |-------------|----------------------|------------------------------------------------| | 200 | OK | Request succeeded | | 400 | Bad Request | Invalid latitude or longitude values | | 401 | Unauthorized | Missing or invalid API key | | 402 | Payment Required | Account has no remaining credits |

Error responses return a JSON body:

{
  "error": "description of the problem"
}

Tips

• Each water lookup costs 1 credit. Use the Account Info endpoint to check the user's balance before making many requests.
• When the user provides a place name instead of coordinates (e.g. "Is the Sahara Desert water?"), geocode the location first to get lat/lon, then call the water lookup endpoint.
• The features array can contain multiple overlapping values for a single point — for example, a point might return both lake and nature_reserve.