## Postman Collection

Import the official collection to explore every endpoint with pre-built environments, example payloads, and scripting helpers.

1. Download the [Near Space Labs Postman collection](https://docs.nearspacelabs.com/assets/files/nsl_postman-3110bc298b59f993c48bc69371b5b6d1.json).
2. Import into Postman and set `NSL_ID` + `NSL_SECRET` env vars.
3. Hit "Send" to test auth, surveys, coverage, and tile downloads in minutes.

## Best Practices

- **Use `If-None-Match` headers** when caching tile responses to avoid re-downloads.
- **Batch coverage queries by AOI** to find the minimal set of tiles before downloading.
- **Rotate tokens proactively** and alert on 401/403 responses to catch expired credentials quickly.
- **Cache footprints** — geometry rarely changes once a survey is published.
- **Page through surveys efficiently** — the default page size is 25. Only fetch what you need.
- **Use v2 endpoints** — legacy `/tile/surveys` routes emit deprecation warnings.

## Token Management

```python
import time

class TokenManager:
    def __init__(self, nsl_id, nsl_secret):
        self.nsl_id = nsl_id
        self.nsl_secret = nsl_secret
        self.token = None
        self.expires_at = 0

def get_token(self):
        # Refresh 5 minutes before expiry
        if time.time() > self.expires_at - 300:
            self.token = get_auth_token(self.nsl_id, self.nsl_secret)
            self.expires_at = time.time() + 3600
        return self.token
```

## Rate Limits & Performance

- Tokens are valid for **60 minutes**.
- The tile service median latency is **~200 ms**.
- For bulk downloads, use the coverage endpoint to precompute the tile list, then parallelize fetches.
- Consider using connection pooling (`requests.Session()` in Python) for repeated requests.