Skip to content
getgeolens.com
GeoLens Docs

Search Post

POST
/stac/search
 
curl --request POST \
  --url https://example.com/stac/search \
  --header 'Content-Type: application/json' \
  --data '{ "bbox": [ -77.2, 38.7, -76.8, 39.1 ], "collections": [ "geolens-unassigned" ], "limit": 25 }'

STAC Item Search (POST with JSON body).

Authorizations

Section titled “Authorizations ”

Request Body required

Section titled “Request Body required ”
Media type application/json
StacSearchBody

JSON body for POST /search.

object
bbox
Any of:
Array<number>
collections
Any of:
Array<string>
datetime
Any of:
string
ids
Any of:
Array<string>
intersects
Any of:
object
key
additional properties
any
limit
Limit

Maximum number of items returned. Values above 200 are clamped to 200.

integer
default: 10 >= 1
offset
Offset

Number of items to skip for pagination.

integer
0

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Successful Response

Media type application/geo+json
StacItemCollectionResponse

Typed OpenAPI representation of a STAC ItemCollection.

object
context
required
StacContext

Paging metadata emitted with STAC ItemCollections.

object
limit
required
Limit
integer
matched
required
Matched
integer
returned
required
Returned
integer
key
additional properties
any
features
required
Features
Array<object>
StacItemResponse

A GeoJSON Feature conforming to the STAC Item specification.

object
assets
required
Assets
object
key
additional properties
StacItemAsset

A STAC asset attached to an Item.

object
description
Any of:
string
href
required
Href

URL of the asset resource.

string
roles
Any of:
Array<string>
title
Any of:
string
type
Any of:
string
key
additional properties
any
bbox
Any of:
array
>= 4 items <= 4 items
collection
Any of:
string
geometry
required
Any of:
GeoJSONGeometryCollection

A GeoJSON GeometryCollection (RFC 7946 §3.1.8).

fix(#430 codex r9): carries geometries instead of coordinates, so it needs its own model — only generic-GEOMETRY datasets accept it on write (enforced in the service), and any stored collection must serialize back out on read.

Deliberately NON-recursive (codex r13, refuted): PostGIS cannot round-trip nested collections through the GeoJSON boundary in either direction — ST_GeomFromGeoJSON rejects them on write and ST_AsGeoJSON raises ‘GeoJson: geometry not supported’ on read — so a recursive model could never receive one and would only convert the write-side 422 into a raw database 500. The write schemas add a raw-payload guard for a clear 422.

object
geometries
required
Geometries
Array<object>
GeoJSONGeometry

A GeoJSON geometry object (RFC 7946).

object
coordinates
required
Coordinates
Array
type
required
Type
string
Allowed values: Point MultiPoint LineString MultiLineString Polygon MultiPolygon
type
required
Type
string
Allowed value: GeometryCollection
id
required
Id

Stable item identifier.

string
links
required
Links
Array<object>
StacLink

A single STAC link object.

object
href
required
Href

Target URL of the link.

string
method
Any of:
string
rel
required
Rel

Link relation type (e.g. ‘self’, ‘root’, ‘parent’, ‘item’, ‘data’).

string
type
Any of:
string
properties
required
StacItemProperties

Core STAC Item properties plus extension-defined fields.

object
datetime
required
Any of:
string
description
Any of:
string
end_datetime
Any of:
string
start_datetime
Any of:
string
title
Any of:
string
key
additional properties
any
stac_extensions
Stac Extensions

STAC extension schema URIs in use.

Array<string>
stac_version
required
Stac Version

STAC specification version.

string
type
Type
string
default: Feature
Allowed value: Feature
key
additional properties
any
links
required
Links
Array<object>
StacLink

A single STAC link object.

object
href
required
Href

Target URL of the link.

string
method
Any of:
string
rel
required
Rel

Link relation type (e.g. ‘self’, ‘root’, ‘parent’, ‘item’, ‘data’).

string
type
Any of:
string
numberMatched
required
Numbermatched
integer
numberReturned
required
Numberreturned
integer
type
Type
string
default: FeatureCollection
Allowed value: FeatureCollection
key
additional properties
any
Example 
{
  "context": {
    "limit": 10,
    "matched": 0,
    "returned": 0
  },
  "features": [],
  "links": [],
  "numberMatched": 0,
  "numberReturned": 0,
  "type": "FeatureCollection"
}

400

Section titled “400 ”

Bad request — invalid query parameters or payload

Media type application/problem+json
ProblemDetail
object
detail
required
Any of:
string
status
required
Status
integer
title
required
Title
string
type
Type
string
default: about:blank
Example 
{
  "detail": "Dataset not found",
  "status": 404,
  "title": "Not Found",
  "type": "about:blank"
}

404

Section titled “404 ”

Not found

Media type application/problem+json
ProblemDetail
object
detail
required
Any of:
string
status
required
Status
integer
title
required
Title
string
type
Type
string
default: about:blank
Example 
{
  "detail": "Dataset not found",
  "status": 404,
  "title": "Not Found",
  "type": "about:blank"
}

429

Section titled “429 ”

Too many requests — retry after the advertised interval

Media type application/problem+json
ProblemDetail
object
detail
required
Any of:
string
status
required
Status
integer
title
required
Title
string
type
Type
string
default: about:blank
Example 
{
  "detail": "Dataset not found",
  "status": 404,
  "title": "Not Found",
  "type": "about:blank"
}

Headers

Section titled “Headers ”
Retry-After
integer

Seconds until the request may be retried

500

Section titled “500 ”

Internal server error

Media type application/problem+json
ProblemDetail
object
detail
required
Any of:
string
status
required
Status
integer
title
required
Title
string
type
Type
string
default: about:blank
Example 
{
  "detail": "Dataset not found",
  "status": 404,
  "title": "Not Found",
  "type": "about:blank"
}

503

Section titled “503 ”

Service unavailable — the database could not serve the request

Media type application/problem+json
ProblemDetail
object
detail
required
Any of:
string
status
required
Status
integer
title
required
Title
string
type
Type
string
default: about:blank
Example 
{
  "detail": "Dataset not found",
  "status": 404,
  "title": "Not Found",
  "type": "about:blank"
}