Developer Platform

The Geopera Developer Platform provides comprehensive APIs, SDKs, and tools for integrating satellite imagery into your applications.

Platform Overview

Our developer platform offers:

  • RESTful APIs for imagery search, ordering, and processing
  • Real-time webhooks for order status updates
  • Multiple SDKs supporting Python, JavaScript, and R
  • Comprehensive documentation with interactive examples
  • Sandbox environment for testing and development

Quick Start

1. Get Your API Key

Sign up for a developer account at portal.geopera.com and generate your API key.

2. Make Your First API Call

bash 
curl -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "aoi": {
      "type": "Polygon",
      "coordinates": [[
        [-122.4194, 37.7749],
        [-122.4094, 37.7749],
        [-122.4094, 37.7849],
        [-122.4194, 37.7849],
        [-122.4194, 37.7749]
      ]]
    },
    "date_range": {
      "start": "2024-01-01",
      "end": "2024-12-31"
    },
    "sensors": ["worldview-3"]
  }' \
  https://api.geopera.com/v1/search

3. Process the Results

json 
{
	"status": "success",
	"data": {
		"scenes": [
			{
				"scene_id": "WV03_20240315_104001_123456",
				"sensor": "worldview-3",
				"acquisition_date": "2024-03-15T10:40:01Z",
				"cloud_cover": 5.2,
				"resolution": 0.3,
				"area_coverage": 98.5
			}
		],
		"total_count": 1
	}
}

Core APIs

Search API

Find satellite imagery matching your criteria:

Endpoint: POST /v1/search

Key Parameters:

  • aoi: Area of Interest (GeoJSON geometry)
  • date_range: Temporal filter
  • sensors: Specific satellite sensors
  • cloud_cover_max: Maximum acceptable cloud coverage
  • resolution_min/max: Spatial resolution requirements

Order API

Place orders for imagery processing and delivery:

Endpoint: POST /v1/orders

Processing Options:

  • ortho: Orthorectified imagery
  • pansharpened: Enhanced resolution
  • analytics_ready: Radiometrically corrected
  • custom: Tailored processing workflows

Status API

Monitor order progress and download results:

Endpoint: GET /v1/orders/{order_id}

Status Values:

  • received: Order accepted
  • processing: Currently being processed
  • completed: Ready for download
  • failed: Processing encountered errors

SDKs and Libraries

Python SDK

python 
pip install geopera-sdk

import geopera

client = geopera.Client(api_key="your-key")

# Search for imagery
results = client.search(
    aoi=my_polygon,
    date_range=("2024-01-01", "2024-12-31"),
    sensors=["worldview-3", "worldview-2"]
)

# Place an order
order = client.order(
    scenes=results.scenes[:3],
    processing_level="ortho",
    output_format="geotiff"
)

# Monitor progress
while order.status != "completed":
    time.sleep(30)
    order.refresh()

# Download results
order.download(directory="./imagery")

JavaScript SDK

javascript 
npm install @geopera/sdk

const Geopera = require('@geopera/sdk');
const client = new Geopera({ apiKey: 'your-key' });

// Async/await pattern
const results = await client.search({
  aoi: myPolygon,
  dateRange: ['2024-01-01', '2024-12-31'],
  sensors: ['worldview-3']
});

const order = await client.createOrder({
  scenes: results.scenes.slice(0, 3),
  processingLevel: 'ortho'
});

// Using webhooks for status updates
order.onStatusChange((status) => {
  console.log(`Order status: ${status}`);
  if (status === 'completed') {
    order.download('./downloads/');
  }
});

R Package

r 
install.packages("geopera")

library(geopera)

# Initialize client
client <- geopera_client(api_key = "your-key")

# Search imagery
results <- search_imagery(
  client = client,
  aoi = my_sf_polygon,
  date_range = c("2024-01-01", "2024-12-31"),
  sensors = c("worldview-3")
)

# Create order
order <- create_order(
  client = client,
  scenes = results$scenes[1:3, ],
  processing_level = "ortho"
)

# Download when ready
download_order(client, order$order_id, "./imagery/")

Authentication Methods

API Key Authentication

Most common method for server-side applications:

bash 
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.geopera.com/v1/search

OAuth 2.0

For web applications requiring user consent:

javascript 
// Redirect to authorization server
window.location.href = `https://auth.geopera.com/oauth/authorize?
  client_id=${CLIENT_ID}&
  response_type=code&
  scope=imagery:read imagery:order&
  redirect_uri=${REDIRECT_URI}`;

// Handle callback and exchange code for token
const token = await exchangeCodeForToken(authorizationCode);

Service Account Keys

For server-to-server communication in enterprise environments:

python 
from geopera import ServiceAccountClient

client = ServiceAccountClient(
    service_account_file="path/to/service-account.json",
    project_id="your-project-id"
)

Rate Limiting

API requests are subject to rate limits:

  • Standard Tier: 1,000 requests/hour
  • Professional Tier: 5,000 requests/hour
  • Enterprise Tier: Custom limits

Rate limit headers in responses:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

Webhooks

Receive real-time notifications about order status changes:

Setting Up Webhooks

python 
client.create_webhook(
    url="https://your-app.com/webhooks/geopera",
    events=["order.completed", "order.failed"],
    secret="your-webhook-secret"
)

Webhook Payload

json 
{
	"event": "order.completed",
	"order_id": "ord_123456",
	"timestamp": "2024-01-15T10:30:00Z",
	"data": {
		"download_urls": [
			"https://downloads.geopera.com/orders/ord_123456/scene1.tif",
			"https://downloads.geopera.com/orders/ord_123456/scene2.tif"
		],
		"processing_report": {
			"total_scenes": 2,
			"successful": 2,
			"failed": 0
		}
	}
}

Error Handling

The API uses standard HTTP status codes and provides detailed error information:

Common Error Codes

  • 400 Bad Request: Invalid request parameters
  • 401 Unauthorized: Invalid or missing API key
  • 403 Forbidden: Insufficient permissions
  • 404 Not Found: Resource not found
  • 429 Too Many Requests: Rate limit exceeded
  • 500 Internal Server Error: Server-side error

Error Response Format

json 
{
	"error": {
		"code": "INVALID_AOI",
		"message": "The provided area of interest is invalid",
		"details": {
			"field": "aoi",
			"issue": "Polygon coordinates are malformed",
			"suggestion": "Ensure coordinates follow GeoJSON specification"
		}
	}
}

Sandbox Environment

Test your integration safely:

  • Base URL: https://sandbox-api.geopera.com/v1/
  • Sample data: Pre-loaded test imagery
  • No billing: Free for development and testing
  • Rate limits: Reduced limits for fair usage

Getting Help

  • Documentation: Complete API reference
  • Code Examples: Sample applications in multiple languages
  • Developer Support: [email protected]
  • Community Forum: Connect with other developers
  • Status Page: status.geopera.com