# NGSI-LD and FiLiP

**NGSI-LD** is an ETSI standard API to read, write and subscribe to data about real-world entities. Every entity has an `id`, a `type` and attributes, and a JSON-LD `@context` that gives the attributes their meaning, usually from [Smart Data Models](<https://citcomai-hub.github.io/toolbox/smart_data_models/index.md>). In the [MIMs](<https://citcomai-hub.github.io/getting_started/interoperability/#mims>) the two go together: *Smart Data Models with NGSI-LD* is the main mechanism of MIM2.

## The calls you need most

| Call | Does |
| --- | --- |
| `GET /ngsi-ld/v1/entities?type=WasteContainer&limit=100` | List entities of a type |
| `GET /ngsi-ld/v1/entities?type=WasteContainer&q=fillingLevel>0.8` | Filter by attribute |
| `GET /ngsi-ld/v1/entities/{id}` | One entity |
| `…&options=keyValues` | Only the values, without the NGSI-LD structure |
| `POST /ngsi-ld/v1/entityOperations/upsert` | Create or update several entities |
| `POST /ngsi-ld/v1/subscriptions` | Be notified of changes |

Send `Accept: application/ld+json` to get the `@context` inside the body.

## FiLiP

[FiLiP](<https://github.com/RWTH-EBC/FiLiP>) (FIWARE Library for Python), by RWTH Aachen, is a Python client for FIWARE APIs, NGSI-LD included, with Pydantic models for the entities. CitCom uses it in the [MIAIS](<https://citcomai-hub.github.io/miais/index.md>).

```bash
pip install filip
```

```python
from filip.clients.ngsi_ld.cb import ContextBrokerLDClient
from filip.models.base import FiwareLDHeader

cb = ContextBrokerLDClient(url="http://localhost:1026", fiware_header=FiwareLDHeader())
containers = cb.get_entity_list(entity_type="WasteContainer", limit=100)
```

```python
from filip.clients.ngsi_ld.cb import ContextBrokerLDClient
from filip.models.base import FiwareLDHeader
from ds_consumer_auth import data_space_session

cb = ContextBrokerLDClient(
    url="https://apisix-townhall-vlc.citcom-vrain-dataspace.eu/lepus",
    session=data_space_session(),  # see ds-consumer-auth
    fiware_header=FiwareLDHeader(),
    create_tenant=False,
)
containers = cb.get_entity_list(entity_type="WasteContainer", limit=100)
```

The code is the same at both levels; only the session changes. See [ds-consumer-auth](<https://citcomai-hub.github.io/toolbox/ds_consumer_auth/index.md>).

## Brokers

| Broker | Notes |
| --- | --- |
| [Orion-LD](<https://github.com/FIWARE/context.Orion-LD>) | FIWARE, MongoDB. Used in Valencia for the traffic state |
| [Scorpio](<https://github.com/ScorpioBroker/ScorpioBroker>) | NEC, PostgreSQL. Comes with the FIWARE Data Space Connector |
| [Lepus](<https://citcomai-hub.github.io/toolbox/lepus/index.md>) | Not a broker: serves an NGSI-v2 broker as NGSI-LD |

> [!TIP]
>
> **Learn more**
>
> - The NGSI-LD specification, now maintained by ETSI TC DATA: the [Core API](<https://www.etsi.org/deliver/etsi_ts/104100_104199/104175/01.01.01_60/ts_104175v010101p.pdf>) (ETSI TS 104 175, September 2026, which supersedes ETSI GS CIM 009) and the [Information Model](<https://www.etsi.org/deliver/etsi_ts/104100_104199/104178/01.01.01_60/ts_104178v010101p.pdf>) (ETSI TS 104 178).
> - The FIWARE [NGSI-LD step-by-step tutorials](<https://ngsi-ld-tutorials.readthedocs.io/>).
