6.4 Use Case: Retrieve or query agriculture parcel(s) modelled as composite digital twins (UC3)

Use Case 3 (UC3) is retrieving (or querying for) agriculture parcel(s) modelled as composite digital twins. Figure 6.4-1 visualizes this scenario.

Figure 6.4-1: UC3 - Retrieve agricultural parcel

The NGSI-LD Entity Type used is AgriParcel, also from the NGSI-LD compatible Smart Data Model[i.5] on Agrifood. For this purpose, we are interested in the following properties and relationships of AgriParcel: - soil type - crop type - location - prediction (relationship to Weather Forecast) - observation (relationship to Weather Station)

Entities of type WeatherStation have at least the following properties: - temperature - humidity

Entities of type WeatherForecast have at least the following properties: - temperature - humidity - wind speed

The retrieve operation for a specific AgriParcel (AgriParcel:001) looks as follows:

GET /ngsi-ld/v1/entities/urn:ngsi-ld:AgriParcel:001? format=concise&join=inline&joinLevel=1
Accept: application/json
Host: localhost:9090
Link: <http://example.org/myContext.jsonld>; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"

Introducing a join and joinLevel allows following the relationships and integrating the entities pointed to by the relation into the result, creating a hierarchy of entities.

Excerpt of result:

{
  "id": "urn:ngsi-ld:AgriParcel:001",
  "type": “AgriParcel",
  "soilType": "Loamy",
  "prediction": {
    "object": "urn:ngsi-ld:WeatherForecast:XXX",
    "objectType": “WeatherForecast", 
    "entity": {
        "id": "urn:ngsi-ld:WeatherForecast:XXX ",
        "type": “WeatherForecast",
        "humidity": {"value": 98, "unitCode: "PCT"},
        "temperature": {"value": 30, "unitCode: "CEL"},
        "windSpeed": {"value": 3, "unitCode: "MPH"}
  }},
  “observation": {
    "object": "urn:ngsi-ld:WeatherObserved:001",
    "objectType": “WeatherObserved",
    "entity": {
        "id": "urn:ngsi-ld:WeatherObserved:001",
        "type": “WeatherObserved",
    ...
}

If the specific AgriParcel is not a-priori known, a query for NGSI-LD Entities of type AgriParcel with a geographic scope can be used as in UC1 and UC2.

GET /ngsi-ld/v1/entities/?type=AgriParcel&geoproperty=location&georel=near%3BmaxDistance==1000&geometry=Point&coordinates=[57.5522023,-20.34840123]&format=concise&join=inline&joinLevel=1
Accept: application/json
Host: localhost:9090
Link: <http://example.org/myContext.jsonld>; rel="http://www.w3.org/ns/json-ld#context"; type="application/ld+json"

The advantages for the application are the following: - Application can request information by specifying what it needs (“information about parcel(s) of land together with respective weather info”) - Application gets results with a single request (unless paging is required due to number of results) - Application can geographically scope the request (for the query) - Application can request that relationships are followed, and the related entities are embedded (up to a given depth) in the result

In order to do this, the application needs to know the following: - Data model: - type: AgriParcel - Relationships (worth following): observation, prediction - GeoProperty name: location - Root URL: localhost:9090