Sandbox Environment
The Sandbox environment lets you build and test against the full Epoch API without touching production data or waiting on real geospatial analysis. It exposes exactly the same endpoints, request shapes, response formats, and authentication as the live API โ so anything you build against the sandbox will work unchanged against production.
The key difference is what happens behind the scenes: in the sandbox, the geospatial analysis backend is emulated rather than run for real.
โถWhat "emulated" means
When you upload locations and request metrics (deforestation, biodiversity, emissions, water stress, etc.), the live API runs them through Epoch's real geospatial pipeline โ satellite imagery analysis, model inference, and cadastral lookups that take real compute time and produce scientifically meaningful results.
The sandbox replaces that pipeline with a lightweight emulator. The emulator:
- Accepts the same uploads and returns the same job/tracking responses.
- Simulates processing time, then marks jobs complete (or, occasionally, failed โ to let you exercise error handling).
- Writes realistic but synthetic data into all the same response fields and tables โ facilities, sheds, plots, and every metric type.
From the API's perspective the round-trip is identical: you upload, you poll for status, you read back fully-populated locations and metrics. Only the meaning of the numbers differs.
โถBenefits of the sandbox
- Fast feedback. Jobs complete in seconds instead of the minutes-to-hours a real geospatial run can take. You can iterate on an integration end-to-end in a single sitting.
- Free and unmetered. No real satellite analysis or compute is consumed, so you can run as many uploads and metric requests as you like.
- Safe. Nothing you do affects production data, real customer records, or compliance submissions.
- Complete shape coverage. Every response field, status, format, and pagination behaviour is present, so you can build and validate your client against the real contract.
- Deterministic enough to test failure paths. The emulator deliberately simulates occasional job failures and validation errors, letting you confirm your retry and error-handling logic works before going live.
The sandbox is the recommended place to develop your integration, write automated tests, and demo workflows.
โถGaps vs. the live API
The sandbox is faithful to the API contract, but because results are synthetic there are some behaviours you should be aware of. Treat the sandbox as correct for structure and workflow, and the live API as correct for values and scientific accuracy.
| Area | Sandbox (emulated) | Live API |
|---|---|---|
| Result set size | A small, representative subset โ enough to exercise pagination, formats, and shapes | Full result sets, which can be far larger (thousands to millions of rows for big uploads) |
| Metric values | Synthetic / randomised, with no relationship to the real-world location you uploaded | Real results derived from satellite imagery and Epoch's models |
| Deforestation, biodiversity, emissions, water stress | Plausible-looking placeholder numbers and flags | Genuine analysis for the supplied geometry and time range |
| Validation & normalisation | Heuristic scoring; will not catch all real-world data-quality issues | Full validation pipeline |
| Processing time | Seconds, with artificial delays | Reflects real workload, can be minutes or longer |
| Job success/failure | Partly random, to simulate failure conditions | Reflects the actual outcome of the analysis |
| Geocoding | May return placeholder or no coordinates for address-only uploads | Real geocoding |
| Thumbnails & imagery | Sample / representative imagery, not your location | Imagery for your actual location |
| Reproducibility | Re-uploading the same data can produce different synthetic values | Stable, repeatable results for the same inputs |
โถPractical implications
- Don't make scientific or compliance decisions from sandbox numbers. They are for wiring up and testing your integration only.
- Expect smaller result sets than production. The sandbox returns a representative subset, so a query that returns a handful of rows here may return thousands or millions against the live API. Build and test your pagination and streaming handling (cursor-walking, NDJSON consumption) on the sandbox so it's ready for the larger volumes production returns โ don't assume a result set fits in a single page. See Response Formats and Query Parameters.
- Don't assert on exact metric values in automated tests โ assert on response shape, field presence, status transitions, and pagination instead.
- Expect occasional simulated failures. This is intentional; build your client to handle them.
- EUDR / DDS outputs in the sandbox are not real submissions and carry no regulatory weight.
โถMoving to production
Because the sandbox mirrors the production API contract exactly, promoting your integration is simply a matter of switching the environment (and using a production API key). No code changes to request shapes, headers, or response parsing should be required โ only the base URL and credentials change.
See Using this Documentation for how to switch environments in the explorer, and Generating an API Key for credentials.