# SkyWatch EarthCache API

> Geospatial data ordering and delivery APIs for satellite imagery and earth observation data

## REST API

The SkyWatch EarthCache REST API provides comprehensive access to satellite imagery archive search, order management, pricing calculation, and webhook configuration.

- **OpenAPI Version**: 3.1.0
- **API Version**: 1.7
- **Base URL**: https://api.skywatch.co/earthcache
- **Specification**: /openapi-spec.json
- **Authentication**: API key via x-api-key header (no "Bearer" prefix)

### API Categories (Alphabetical)

1. **Archive Search** - Search satellite imagery archives and retrieve results (REST and WebSocket)
2. **Calculate Pricing** - Get pricing information and probability of collection
3. **DirectView** - Browser-based imagery viewing and WMTS tile services
4. **Locations** - Manage spatial data as KML and GeoJSON
5. **Offerings** - Browse satellite imagery products and configurations
6. **Orders (Pipelines)** - Create and manage orders for geospatial data delivery
7. **Payment Methods** - View payment methods for your organization
8. **Projects** - Manage projects for organizing users and billing
9. **Users** - Manage users within your organization
10. **Webhooks** - Subscribe to pipeline event notifications

## WebSocket API

Real-time archive search results streaming.

- **WebSocket URL**: wss://d3so7ozptr7ad5.cloudfront.net/prod
- **Authentication**: JWT token via WebSocket auth message
- **JWT Expiration**: 7200 seconds
- **Max Payload**: 128 KB (~2500 coordinates)

## Documentation Structure

### Overview
- `/docs/intro` - Introduction to the SkyWatch API

### Getting Started
- `/docs/general/api-authentication` - Authentication guide with API key setup
- `/docs/general/best-practices` - Best practices for API usage

### Governance
- `/docs/governance/roles-and-permissions` - User roles (Super Admin, Member, Reader)
- `/docs/governance/billing-and-projects` - Payment methods and project management
- `/docs/accounts/users` - User management
- `/docs/accounts/payment-methods` - Payment method configuration
- `/docs/projects/projects` - Project setup and user access control

### Products & Pricing
- `/docs/products/offerings-and-configs` - Product offerings and configurations
- `/docs/pricing/pricing` - Cost calculation for orders

### Workflows
- `/docs/archive/archive-workflow` - Archive data ordering workflow
- `/docs/tasking/tasking-workflow` - Tasking (future capture) ordering workflow

### Orders
- `/docs/orders/orders` - Order management overview
- `/docs/orders/order-config` - Order configuration and results retrieval
- `/docs/results/directview-wmts` - DirectView and WMTS integration

### Limits & Error Handling
- `/docs/limits-errors` - API constraints, rate limits, and error handling

### API Reference
- `/docs/rest-api` - Interactive REST API reference with OpenAPI integration
  - Archive Search (REST POST/GET and WebSocket)
  - Calculate Pricing (cost and probability endpoints)
  - DirectView (URL generation and custom tiles)
  - Locations (CRUD operations)
  - Offerings (list and get)
  - Orders/Pipelines (create, list, update, delete, results, outputs)
  - Payment Methods (list and get)
  - Projects (create, list, update, delete, user management)
  - Users (list, get current, get by ID)
  - Webhooks (subscriptions and callbacks)

## Key Features

### Archive Search
- REST API endpoints for searching historical satellite imagery
- WebSocket API for real-time search results streaming
- Supports GeoJSON Polygon geometry (WGS84)

### Orders (Pipelines)
- Create, update, list, and delete orders
- Support for both archive and tasking orders
- Interval results for recurring orders
- Output management and delivery

### Hub Management
- User management with role-based access (Super Admin, Member, Reader)
- Project organization for billing and access control
- Payment method configuration
- Offering discovery and configuration

### DirectView & WMTS
- Browser-based imagery viewing
- WMTS tile services for GIS integration
- Custom tile generation

## Important Constraints

### Geometry
- Single Polygon only (GeoJSON, WGS84)
- No holes (donuts) or multipolygons
- Maximum 500 vertices recommended
- Minimum area: 1 km² for archive orders

### Archive Orders
- Minimum AOI: > 1 km²
- Orders are machine-to-machine, no refunds
- Prefer Sentinel-2 (free) for testing

### Tasking Orders
- Minimum interval: 7 days
- Place orders at least 2 days before start
- Cannot cancel within 48 hours of start
- min_aoi_coverage_percentage typically <= 85%
- Output must be geotiff, mosaic unstitched

### WebSocket
- Hard payload limit: 128 KB (~2500 coordinates)
- JWT token expiration: 7200 seconds
- Connection closes automatically after search completes

## Example Coordinates

All examples use NYC coordinates:
```json
{
  "type": "Polygon",
  "coordinates": [
    [
      [-73.95950959050467, 40.803232950312264],
      [-73.98518739769608, 40.768306075577726],
      [-73.97154148035514, 40.761912689996564],
      [-73.94657494129676, 40.79741232310445],
      [-73.95950959050467, 40.803232950312264]
    ]
  ]
}
```

## Servers

- **REST API**: https://api.skywatch.co/earthcache
- **DirectView & WMTS**: https://directview.earthcache.com
- **WebSocket**: wss://d3so7ozptr7ad5.cloudfront.net/prod

## Support

- **Email**: support@skywatch.com
- **Website**: http://support.skywatch.com
- **Documentation**: This site provides interactive documentation for all APIs

## For LLMs

This documentation is designed to be both human-readable and machine-parsable. The OpenAPI specification at `/openapi-spec.json` provides complete endpoint definitions, request/response schemas, and examples. All coordinate examples use real NYC coordinates to ensure validity. The documentation emphasizes practical workflows and includes important constraints to prevent common errors.