---
title: "Large-site Sentinel-2 imagery pair"
method: POST
path: "/api/locus-large-site-satellite-change"
tags: ["satellite", "sentinel-2", "copernicus", "large-site", "area-change", "construction-monitoring", "land-change", "dated-imagery", "category:infrastructure"]
---

# Large-site Sentinel-2 imagery pair

`POST /api/locus-large-site-satellite-change`

## Request

- Base URL: `https://api.locus.report`
- URL: `https://api.locus.report/api/locus-large-site-satellite-change`
- Auth: API key in header `PAYMENT-SIGNATURE`

Two dated Copernicus Sentinel-2 images for WGS84 bbox and ordered beforeDate/afterDate. Use locus_satellite_area_prepare for addresses. Area 1-100 sq km; sides >=500m, aspect <=8:1. Metadata by default; includeImagery inlines PNGs. No change detection; source failure is free. REST-only. npx @velinussage/locus-agent-skill add.

## Request body

- object
  - `areaLabel` string: Optional non-person site label. It is presentation only and is not sent to the imagery provider.
  - `bbox` unknown[], required: Requires bbox [west, south, east, north] in WGS84 longitude/latitude; no address input. Area 1-100 km², each side at least 500 m, aspect ratio at most 8:1. Surrounding-area context, not individual-building imagery.
    - unknown
  - `beforeDate` string, date, required: Anchor date for the earlier composite.
  - `afterDate` string, date, required: Anchor date for the later composite; must be later than beforeDate.
  - `windowDays` integer
  - `size` integer
  - `maxCloudCoverage` integer
  - `includeImagery` boolean: Inline the two validated PNG renders as base64. Off by default: a 512 px pair pushes the response past 128 KB and breaks naive JSON capture. The dated catalogue metadata, byte sizes, and pixel dimensions are always returned.

## Response `200`

Successful paid artifact, or a free pre-charge diagnostic when the request is outside current coverage.

- union
  - object
    - `kind` 'large_site_satellite_change', required
    - `generatedAt` string, required
    - `priceUsdc` '0.15', required
    - `analysisScale` 'area_only', required
    - `area` object, required
      - `label` string
      - `bbox` unknown[], required
        - unknown
      - `widthMeters` number, required
      - `heightMeters` number, required
      - `areaSquareMeters` number, required
    - `imagery` object, required
      - `source` 'cdse-sentinel-2-l2a', required
      - `format` 'png', required
      - `contentType` 'image/png', required
      - `windowDays` integer, required
      - `maxCloudCoveragePercent` number, required
      - `widthPixels` integer, required
      - `heightPixels` integer, required
      - `before` object, required
        - `anchorDate` string, required
        - `rangeFrom` string, required
        - `rangeTo` string, required
        - `bytes` integer, required
        - `dataBase64` string
        - `processingUnits` number
        - `catalogCandidates` object[], required
          - `id` string, required
          - `acquisitionTime` string, required
          - `publishedTileCloudCoverPercent` number
          - `platform` string
          - `gridCode` string
          - `processingLevel` string
          - `sourceLocator` string, uri, required
      - `after` object, required
        - `anchorDate` string, required
        - `rangeFrom` string, required
        - `rangeTo` string, required
        - `bytes` integer, required
        - `dataBase64` string
        - `processingUnits` number
        - `catalogCandidates` object[], required
          - `id` string, required
          - `acquisitionTime` string, required
          - `publishedTileCloudCoverPercent` number
          - `platform` string
          - `gridCode` string
          - `processingLevel` string
          - `sourceLocator` string, uri, required
      - `license` string, required
      - `attribution` string, required
    - `source` object, required
      - `sourceName` 'Copernicus Data Space Ecosystem Sentinel-2', required
      - `sourceUrl` string, uri, required
      - `fetchedAt` string, required
      - `usePolicy` object, required
        - `paidResponse` 'allowed' | 'allowed_with_attribution' | 'not_verified', required
        - `cache` 'allowed' | 'ephemeral_only' | 'no_store', required
        - `attributionRequired` boolean, required
        - `attributionText` string
        - `downstreamRedistribution` 'allowed' | 'restricted' | 'not_verified', required
        - `publicPinning` 'allowed' | 'prohibited' | 'not_verified', required
        - `policyUrl` string, uri, required
        - `verifiedAt` string, required
    - `costModel` object, required
      - `sourceAccessCostUsd` '0', required
      - `renderRequests` 2, required
      - `quotaModel` 'cdse_general_user_monthly_quota', required
      - `turnkeyRequired` false, required
      - `pricingBasis` 'locus_scene_discovery_render_validation_and_delivery', required
    - `interpretationGuide` object
      - `resolution` string, required
      - `whatCounts` string[], required
      - `falseChange` string[], required
      - `method` string[], required
      - `modelPrompt` string, required
      - `limits` string, required
      - `practitionerReadings` object[]
        - `observation` string, required
        - `reading` string, required
        - `forWhom` string[], required
        - `askNext` string[], required
      - `urgencyCue` string
    - `caveats` string[], required
    - `verifyNext` object[], required
      - `step` string, required
      - `sourceUrl` string, uri
    - `charged` false
  - object
    - `kind` 'large_site_satellite_change_diagnostic', required
    - `generatedAt` string, required
    - `status` 'not_configured' | 'source_unavailable' | 'invalid_source_response' | 'no_scenes' | 'quota_unavailable', required
    - `charged` false, required
    - `message` string, required
    - `caveats` string[], required
  - object
    - `kind` 'large_site_satellite_change_replay', required
    - `status` 'licensed_result_not_retained', required
    - `generatedAt` string, required
    - `message` string, required
    - `originalResultDelivered` true, required
    - `recheckRequired` true, required
    - `sourcePolicy` object, required
      - `sourceName` string, required
      - `cache` 'allowed' | 'ephemeral_only' | 'no_store', required
      - `downstreamRedistribution` 'allowed' | 'restricted' | 'not_verified', required
      - `publicPinning` 'allowed' | 'prohibited' | 'not_verified', required
      - `policyUrl` string, uri, required

## Other responses

- `400`: Invalid satellite input, rejected before payment or imagery access. Bounded issues identify fields and corrections; requires bbox, beforeDate and afterDate, not address. Empty unpaid scanner probes remain 402.
- `402`: Payment Required. For x402 v2, repeat the identical request with a valid PAYMENT-SIGNATURE header (legacy X-PAYMENT is accepted for compatibility). MPP is disabled for this lifecycle-bound tool.

---

[API](https://skmtc.dev/locus/apis/locus-api.md) · [All operations](https://skmtc.dev/locus/apis/locus-api/llms.txt) · [OpenAPI document](https://skmtc.dev/locus/apis/locus-api/revisions/ba7786b74adb?raw)