SoilSense API (beta)

To use the SoilSense API, you'll need to create an API key:

1. Log in to your SoilSense account at app.soilsense.io
2. Navigate to Settings (cog icon next to the farm name) → Farm
3. Scroll down to the API KEYS section
4. Click "Create API Key"
5. Give your key a name (e.g., "My Integration", "Weather App")
6. Copy the generated key - you won't be able to see it again!
7. Store it securely - treat it like a secret password

curl -H "x-api-key: YOUR_API_KEY_HERE" \
     https://api.app.soilsense.io/api/farm

You can try the endpoints out in our Swagger interface at https://api.app.soilsense.io/swagger.

All API endpoints require authentication using an API key in the request header:

x-api-key: your_api_key_here

⚠️ Security: Never expose your API key in client-side code or public repositories.

The API implements universal rate limiting that applies consistently across all endpoints:

All limits are applied per API key (or IP address if no API key is provided):

• Per second: 20 requests per second
• Per minute: 600 requests per minute
• Per hour: 10,000 requests per hour

All three rate limits are enforced simultaneously.

Any single limit can block your request. The rate limit headers in the response show information from the most recently applied rate limiter.

Every response includes rate limit information:

RateLimit-Limit: 600
RateLimit-Remaining: 287
RateLimit-Reset: 2024-06-25T14:30:00.000Z
RateLimit-Policy: 600;w=60

• RateLimit-Limit: Maximum requests allowed in the current window
• RateLimit-Remaining: Requests remaining in current window
• RateLimit-Reset: When the current window resets (ISO 8601)
• RateLimit-Policy: Rate limit policy in format limit;w=window_seconds

When you exceed any rate limit, you'll receive a 429 status with error message.

The API uses standard HTTP status codes to indicate the success or failure of API calls:

• 200 OK - Request successful

• 400 Bad Request - Invalid request parameters

• 401 Unauthorized - Missing or invalid API key

• 403 Forbidden - API key valid but lacks permission for this resource

• 404 Not Found - Resource not found

• 429 Too Many Requests - Rate limit exceeded

• 500 Internal Server Error - Server-side error

All error responses follow this JSON format:

{
  "error": "Description of what went wrong"
}

{
  "error": "Rate limit exceeded. Maximum 300 requests per minute."
}

Retrieve farm information and observation site information

Retrieve soil observations and precipitation data for observation sites

const API_KEY = 'YOUR_API_KEY_HERE';
const BASE_URL = 'https://api.app.soilsense.io';

// Get observation sites
const sitesResponse = await fetch(`${BASE_URL}/api/farm/sites`, {
  headers: { 'x-api-key': API_KEY }
});
const sites = await sitesResponse.json();

// Calculate last week timestamps (Unix timestamps in milliseconds)
const endTime = Date.now();
const startTime = endTime - (7 * 24 * 60 * 60 * 1000); // 7 days ago

// Loop through sites with rate limiting in mind
for (const site of sites) {
  // Get site details
  const siteDetailResponse = await fetch(
    `${BASE_URL}/api/farm/site/${site.id}`,
    { headers: { 'x-api-key': API_KEY } }
  );
  const siteDetails = await siteDetailResponse.json();

  // Get observations for last week using Unix timestamps
  const observationsResponse = await fetch(
    `${BASE_URL}/api/site/${site.id}/observations?startTime=${startTime}&endTime=${endTime}`,
    { headers: { 'x-api-key': API_KEY } }
  );
  const observations = await observationsResponse.json();

  console.log(`Site: ${siteDetails.name}, Observations:`, observations);
  
  // Optional: Add small delay between requests to stay well within rate limits
  await new Promise(resolve => setTimeout(resolve, 100)); // 100ms delay
}

Configure webhook URLs in the SoilSense interface under device settings.

SoilSense will automatically send data to your configured endpoints:

• Telemetry data → POST {your_webhook_url}/telemetry
• Device attributes → POST {your_webhook_url}/attributes