Search examples

The unified endpoint queries Knowledge Packages and Knowledge Resources together in a single request. This page walks through the parameters and the most common query shapes.

Endpoint

GET /api/search

No authentication is required to search public content.

Query parameters

Parameter	Type	Description
q	string	Query in Elasticsearch query string syntax.
bbox	string	Bounding box lon,lat,lon,lat — top-left longitude/latitude, bottom-right longitude/latitude.
sort	string	Sort field and direction (e.g. newest, oldest, bestmatch).
size	integer	Results per page. Default: 10.
page	integer	Page number (1-indexed).
allversions	boolean	Include all versions in the results, not just the latest.

The response shape mirrors InvenioRDM’s standard search payload:

{
  "aggregations": { ... },
  "hits": {
    "total": 42,
    "hits": [ /* records */ ]
  },
  "links": { ... },
  "sortBy": "bestmatch"
}

Need the per-entity endpoints?

The same query syntax also works against /api/packages (Packages only) and /api/records (Resources only) — see the interactive OpenAPI reference for the full parameter set.

Common queries

Full-text search

Find Packages and Resources matching a free-text query, paginated:

HTTP

GET /api/search?q=flood+mapping&size=10&page=1 HTTP/1.1
Host: gkhub.earthobservations.org
Accept: application/json

cURL

curl "https://gkhub.earthobservations.org/api/search?q=flood+mapping&size=10&page=1" \
  -H "Accept: application/json"

Spatial filter

Restrict results to records whose geometry intersects a bounding box. The two coordinate pairs are top-left and bottom-right, in lon, lat, lon, lat order:

HTTP

GET /api/search?bbox=-1.538086,6.54201,0.791016,4.879216 HTTP/1.1
Host: gkhub.earthobservations.org
Accept: application/json

cURL

curl "https://gkhub.earthobservations.org/api/search?bbox=-1.538086,6.54201,0.791016,4.879216" \
  -H "Accept: application/json"

Filter by engagement priority (e.g. SDGs)

Use field-scoped queries to filter against GEO-specific vocabularies. The example below returns records tagged with SDG 13 (Climate Action):

HTTP

GET /api/search?q=metadata.engagement_priorities.id:sdg-goal-13 HTTP/1.1
Host: gkhub.earthobservations.org
Accept: application/json

cURL

curl "https://gkhub.earthobservations.org/api/search?q=metadata.engagement_priorities.id:sdg-goal-13" \
  -H "Accept: application/json"

Combining filters

Field queries can be combined with free-text queries and boolean operators. The example below finds Packages and Resources that mention “Sentinel-2” and are tagged with the GEO Land theme:

HTTP

GET /api/search?q=Sentinel-2+AND+metadata.engagement_priorities.id:land HTTP/1.1
Host: gkhub.earthobservations.org
Accept: application/json

cURL

curl "https://gkhub.earthobservations.org/api/search?q=Sentinel-2+AND+metadata.engagement_priorities.id:land" \
  -H "Accept: application/json"

More query patterns

The query string syntax used in the examples below is the standard Elasticsearch dialect.

To learn more about it and how to use it in the GEO Knowledge Hub, please refer to the Search guide page. On this page, you will find a catalogue of patterns, like phrases, fuzziness, boosting, wildcards, ranges, etc., that all work with the GEO Knowledge Hub Search API.