OnWater API

Overview

The OnWater API is a focused geospatial service designed to answer a single question: Is a specific geographic coordinate on water or land? It processes latitude and longitude inputs and returns a boolean value, true for water and false for land, along with additional contextual information such as the name of the water body if applicable. This precision makes it a valuable tool for developers building applications that require accurate water-land boundary detection.

Target users for the OnWater API include developers working on maritime logistics, environmental monitoring systems, and location-aware applications. For example, a shipping company might use it to verify if a vessel's reported position is indeed at sea or in a port, while a drone operator could use it to program flight paths that avoid bodies of water. The API's simplicity and singular focus allow for efficient integration without the overhead of more general-purpose geocoding services, which often provide a broader range of data points that may not be relevant for water-detection tasks.

OnWater shines in scenarios where clarity on water presence is paramount. This includes applications for marine safety, fisheries management, and recreational boating, where knowing the exact location relative to water is critical. Its utility extends to urban planning, where it can help identify properties adjacent to water bodies, or in real estate, for filtering listings based on proximity to water. The API's design emphasizes ease of use, providing a direct answer to a common geospatial challenge. Unlike comprehensive mapping platforms that offer extensive features like routing, place search, and elevation data, OnWater specializes in this specific water-detection query, ensuring optimized performance and a streamlined data payload for this precise use case. This specialization allows developers to integrate a highly focused function without needing to process or filter extraneous geospatial data.

For developers who require broad mapping capabilities alongside water detection, a combination of OnWater with a more extensive platform like Google Maps Platform services might be considered. However, for the specific task of determining water presence, OnWater offers a direct and efficient solution. The API's reliance on a simple HTTP GET request with URL parameters for coordinates makes it accessible across various programming environments. Its developer experience is noted for being straightforward, with clear documentation and basic examples facilitating quick adoption for its core functionality.

Key features

• Water-land detection: Determines if a given latitude/longitude coordinate is on a body of water or on land, returning a boolean is_water status.
• Water body identification: Provides the name of the water body (e.g., 'Atlantic Ocean', 'Mississippi River') when a coordinate falls on water.
• API key authentication: Secures access to the API using a unique API key for each user.
• Rate limiting: Manages API usage to ensure fair access and prevent abuse, with different limits based on subscription tiers.
• JSON response format: Returns data in a standard JSON format, making it compatible with most modern web and application development frameworks.
• HTTP GET requests: Utilizes simple HTTP GET requests for querying, allowing for easy integration into client-side and server-side applications.

Pricing

OnWater offers a free tier for initial development and testing, with paid plans available for higher usage volumes. Pricing is structured based on the number of monthly requests.

For detailed and up-to-date pricing information, refer to the official OnWater documentation and pricing page.

Common integrations

The OnWater API's focused functionality makes it suitable for integration into various platforms and applications where water-land distinction is necessary. While no specific SDKs are provided, its RESTful nature allows for integration with any language or environment capable of making HTTP requests. Common integration scenarios include:

• Mapping applications: Enhancing custom maps to display water body information or filter points of interest based on water presence.
• Logistics and delivery platforms: Optimizing routes to avoid water bodies for ground transportation or verifying maritime positions.
• Environmental monitoring systems: Tracking sensor data locations relative to water bodies for ecological studies or pollution control.
• Marine safety applications: Providing real-time water detection for boats, drones, or other aquatic vehicles.
• Real estate platforms: Filtering properties based on whether they are located on land or directly adjacent to water.
• Gaming and simulation: Creating more realistic virtual environments by accurately categorizing terrain as water or land.

Alternatives

While OnWater specializes in water-land detection, several other geospatial APIs offer broader geocoding and mapping capabilities that can sometimes be adapted for similar purposes, albeit with potentially more complex data processing.

• OpenCage Geocoding API: Offers forward and reverse geocoding, including country, state, and city information, which can sometimes infer water presence based on proximity to coastlines or major rivers.
• Google Maps Platform: Provides a comprehensive suite of mapping services, including geocoding, places, and elevation, which could be used to determine water presence through analyzing feature types at a given coordinate.
• Mapbox: A platform for custom maps, location search, and navigation, offering detailed vector tiles that can distinguish between land and water features.

Getting started

To begin using the OnWater API, you first need to obtain an API key, typically available after signing up on their website. The API is accessed via a simple HTTP GET request. Below is an example using Python's requests library to check if a coordinate is on water.

import requests
import json

API_KEY = 'YOUR_ONWATER_API_KEY' # Replace with your actual API key
LATITUDE = 34.0522 # Example: Los Angeles
LONGITUDE = -118.2437

# Coordinate known to be on water (e.g., Pacific Ocean near LA)
WATER_LATITUDE = 33.7380
WATER_LONGITUDE = -118.2816

def check_coordinate(lat, lon, api_key):
    url = f"https://api.onwater.io/api/v1/results/{lat},{lon}?access_token={api_key}"
    try:
        response = requests.get(url)
        response.raise_for_status() # Raise an exception for HTTP errors
        data = response.json()
        return data
    except requests.exceptions.RequestException as e:
        print(f"API request failed: {e}")
        return None

# Check a land coordinate
print(f"Checking land coordinate ({LATITUDE}, {LONGITUDE}):")
land_result = check_coordinate(LATITUDE, LONGITUDE, API_KEY)
if land_result:
    print(json.dumps(land_result, indent=2))

print("\n" + "-" * 30 + "\n")

# Check a water coordinate
print(f"Checking water coordinate ({WATER_LATITUDE}, {WATER_LONGITUDE}):")
water_result = check_coordinate(WATER_LATITUDE, WATER_LONGITUDE, API_KEY)
if water_result:
    print(json.dumps(water_result, indent=2))

This Python script defines a function check_coordinate that constructs the API request URL with the provided latitude, longitude, and API key. It then sends a GET request and parses the JSON response. The example demonstrates checking both a land-based coordinate and a water-based coordinate to illustrate the API's output. The is_water field in the JSON response will indicate whether the point is on water. For more details on request parameters and response fields, consult the OnWater API reference documentation.