{"info":{"_postman_id":"dd7b3ba8-5aa3-405a-b054-47608a483f77","name":"FIWARE Getting Started","description":"Let’s start with the data from a supermarket chain’s store finder and create a very simple *“Powered by FIWARE”* application by passing in the address and location of each store as context data to the FIWARE context broker.\n\nThe `docker-compose` file for this tutorial can be found on GitHub: \n\n![GitHub](https://fiware.github.io/tutorials.Getting-Started/icon/GitHub-Mark-32px.png) [FIWARE 101: An Introduction to the FIWARE Platform](https://github.com/Fiware/tutorials.Getting-Started)\n\n# Architecture\n\nOur demo application will only make use of one FIWARE component - the [Orion Context Broker](https://catalogue.fiware.org/enablers/publishsubscribe-context-broker-orion-context-broker) . Usage of the Orion Context Broker is sufficient for an application to qualify as *“Powered by FIWARE”*.\n\nCurrently, the Orion Context Broker  relies on open source [MongoDB](https://www.mongodb.com/) technology to keep persistence of the context data it holds. Therefore, the architecture will consist of two elements:\n\n* The  Orion Context Broker server which will receive requests using NGSI\n* The underlying MongoDB database associated to the Orion Context Broker server\n\nSince all interactions between the two elements are initiated by HTTP requests, the entities can be containerized and run from exposed ports. \n\n![](https://fiware.github.io/tutorials.Getting-Started/img//architecture.png)\n\n# Prerequisites\n\n## Docker\n\nTo keep things simple both components will be run using [Docker](https://www.docker.com). **Docker** is a container technology which allows to different components isolated into their respective environments. \n\n* To install Docker on Windows follow the instructions [here](https://docs.docker.com/docker-for-windows/)\n* To install Docker on Mac follow the instructions [here](https://docs.docker.com/docker-for-mac/)\n* To install Docker on Linux follow the instructions [here](https://docs.docker.com/install/)\n\n\n\n# Starting the Containers\n\n## Initialization\n\nFirst  pull the necessary Docker images from Docker Hub and create a network for our containers to connect to:\n\n```console \ndocker pull mongo:3.6\ndocker pull fiware/orion\ndocker network create fiware_default\n```\n\n## Start Up\n\nA Docker container running a MongoDB database can be started and connected to the network with the following command:\n\n```console\ndocker run -d --name=context-db --network=fiware_default \\\n  --expose=27017 mongo:3.6 --bind_ip_all --smallfiles\n``` \n\nThe Orion Context Broker can be started and connected to the network with the following command:\n\n```console\ndocker run -d --name orion  --network=fiware_default \\\n  -p 1026:1026  fiware/orion -dbhost context-db\n```   \n\nYou can check if the Orion Context Broker is running by making an HTTP request to the exposed port:\n\n```console\ncurl -X GET http://localhost:1026/version\n```\n\nAlternatively run all your curl commands from within the container network:\n\n```console\ndocker run --network fiware_default --rm appropriate/curl -s \\\n  -X GET http://orion:1026/version\n```\n\n**What if I get an error response?**\n\nIf you get an error response, the Orion Content Broker cannot be found where expected\nfor this tutorial  - you will need to substitute the URL and port in each Postman request \nwith the corrected ip address. All the Postman requests in this tutorial assume \nthat orion is available on `localhost:1026`. \n \nTry the following remedies:\n\n* To check that the dockers container are running try the following:\n\n```console\ndocker ps\n```\n\nYou should see two containers running. If orion is not running, you can restart the \ncontainers as necessary. This command will also display open port information.\n\n* If you have installed [`docker-machine`](https://docs.docker.com/machine/) and [Virtual Box](https://www.virtualbox.org/), you will need to retrieve the virtual host ip as shown:\n\n```console\ncurl -X GET http://$(docker-machine ip default):1026/version\n```\n\nIf you need to update the location of orion:\n\n1. Click on the elipsis `...` at the head of the imported postman collection\n2. Select `edit` from the dropdown\n3. Click on the `variables` tab and alter the value from `localhost:1026` as necessary.","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json"},"item":[{"name":"Obtaining Version Information","id":"8d1d967d-462a-4482-8f86-e543ca64606e","request":{"method":"GET","header":[],"url":"http://{{orion}}/version/","description":"As usual, you can check if the Orion Context Broker is running by making an HTTP request to the exposed port.\n\nThe format of the version response has not changed for Orion NGSI-LD The `release_date` must be 16th July 2019 or later to be able to\nwork with the requests defined below."},"response":[],"_postman_id":"8d1d967d-462a-4482-8f86-e543ca64606e"},{"name":"Creating your first Data Entity","id":"0f9de5f1-ef79-4324-bebe-6def3f08b9fe","request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n    \"id\": \"urn:ngsi-ld:Store:001\",\n    \"type\": \"Store\",\n    \"address\": {\n        \"type\": \"PostalAddress\",\n        \"value\": {\n            \"streetAddress\": \"Bornholmer Straße 65\",\n            \"addressRegion\": \"Berlin\",\n            \"addressLocality\": \"Prenzlauer Berg\",\n            \"postalCode\": \"10439\"\n        },\n        \"metadata\": {\n    \t\t\"verified\": {\n        \t\t\"value\": true,\n        \t\t\"type\": \"Boolean\"\n    \t\t}\n    \t}\n    },\n    \"location\": {\n        \"type\": \"geo:json\",\n        \"value\": {\n             \"type\": \"Point\",\n             \"coordinates\": [13.3986, 52.5547]\n        }\n    },\n    \"name\": {\n        \"type\": \"Text\",\n        \"value\": \"Bösebrücke Einkauf\"\n    }\n}"},"url":"http://{{orion}}/v2/entities/","description":"When creating linked data entities, it is important to use common data models. This will allow us to easily combine data\nfrom multiple sources and remove ambiguity when comparing data coming from different sources.\n\nCreating linked data using full qualified names throughout would be painful, as each attribute would need to be a URN,\nso JSON-LD introduces the idea of an `@context` attribute which can hold pointers to context definitions. To add a\nFIWARE [Building](https://fiware-datamodels.readthedocs.io/en/latest/Building/Building/doc/spec/index.html) data entity,\nthe following `@context` would be required\n\n```json\n{\n    \"id\": \"urn:ngsi-ld:Building:store001\",\n    \"type\": \"Building\",\n    ...  other data attributes\n    \"@context\": [\n        \"https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context.jsonld\",\n        \"https://schema.lab.fiware.org/ld/fiware-datamodels-context.jsonld\"\n    ]\n}\n```\n\n### Core Context\n\n[https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context.jsonld](https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context.jsonld)\nrefers to the Core `@context` of NSGI-LD, this defines element such as `id` and `type` which are common to all NGSI\nentities, as well as defining terms such as `Property` and `Relationship`. The core context is so fundamental to\nNGSI-LD, that it is added by default to any `@context` sent to a request.\n\n### FIWARE Data Models\n\n[https://schema.lab.fiware.org/ld/fiware-datamodels-context.jsonld](https://schema.lab.fiware.org/ld/fiware-datamodels-context.jsonld)\nrefers to the definition of standard data models supplied by FIWARE. Adding this to the `@context` will load the\ndefinitions of all the [data models](https://fiware-datamodels.readthedocs.io) defined by the FIWARE Foundation, a\nsummary of the FQNs related to **Building** can be seen below:\n\n```json\n{\n    \"@context\": {\n        \"Building\": \"https://uri.fiware.org/ns/datamodels/Building\",\n        ... etc\n        \"address\": \"http://schema.org/address\",\n        \"category\": \"https://uri.fiware.org/ns/datamodels/category\",\n        \"location\": \"http://uri.etsi.org/ngsi-ld/location\",\n        \"name\": \"http://schema.org/name\",\n        ...etc\n    }\n}\n```\n\nIf we include this context definition, it means that we will be able to use short names for `Building`, `address`,\n`location` for our entities, but computers will also be able to read the FNQs when comparing with other sources.\n\nTo create a valid **Building** data entity in the context broker, make a POST request to the\n`http://localhost:1026/ngsi-ld/v1/entities` endpoint as shown below. It is essential that the appropriate\n`Content-Type: application/ld+json` is also used, so that the data entity is recognized as Linked data.\n\nThe first request will take some time, as the context broker must navigate and load all of the files mentioned in the\n`@context`."},"response":[],"_postman_id":"0f9de5f1-ef79-4324-bebe-6def3f08b9fe"},{"name":"Creating your Second Data Entity","id":"b503e293-b212-48db-bbb6-b1861793b3bc","request":{"method":"POST","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":"{\n  \"type\": \"Store\",\n    \"id\": \"urn:ngsi-ld:Store:002\",\n    \"address\": {\n        \"type\": \"PostalAddress\",\n        \"value\": {\n            \"streetAddress\": \"Friedrichstraße 44\",\n            \"addressRegion\": \"Berlin\",\n            \"addressLocality\": \"Kreuzberg\",\n            \"postalCode\": \"10969\"\n        },\n        \"metadata\": {\n    \t\t\"verified\": {\n        \t\t\"value\": true,\n        \t\t\"type\": \"Boolean\"\n    \t\t}\n    \t}\n    },\n    \"location\": {\n        \"type\": \"geo:json\",\n        \"value\": {\n             \"type\": \"Point\",\n             \"coordinates\": [13.3903, 52.5075]\n        }\n    },\n    \"name\": {\n        \"type\": \"Text\",\n        \"value\": \"Checkpoint Markt\"\n    }\n}"},"url":"http://{{orion}}/v2/entities/","description":"Each subsequent entity must have a unique `id` for the given `type`\n\n### Defining Properties within the NGSI-LD entity definition\n\nThe attributes `id` and `type` should be familiar to anyone who has used NSGI v2, and these have not changed. As\nmentioned above, the type should refer to an included data model, in this case `Building` is being used as a short name\nfor the inclued URN `https://uri.fiware.org/ns/datamodels/Building`. Thereafter each _property_ is defined as a JSON\nelement containing two attributes, a `type` and a `value`.\n\nThe `type` of a _property_ attribute must be one of the following:\n\n-   `\"GeoProperty\"`: `\"http://uri.etsi.org/ngsi-ld/GeoProperty\"` for locations. Locations should be specified as\n    Longitude-Latitude pairs in [GeoJSON format](https://tools.ietf.org/html/rfc7946). The preferred name for the\n    primary location attribute is `location`\n-   `\"TemporalProperty\"`: `\"http://uri.etsi.org/ngsi-ld/TemporalProperty\"` for time-based values. Temporal properties\n    should be Date, Time or DateTime strings encoded be [ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601) - e.g.\n    `YYYY-MM-DDThh:mm:ssZ`\n-   `\"Property\"`: `\"http://uri.etsi.org/ngsi-ld/Property\"` - for everything else\n\n> **Note:** that for simplicity, this data entity has no relationships defined. Relationships must be given the\n> `type=\"Relationship`. Relationships will be discusssed in a subsequent tutorial.\n\n### Defining Properties-of-Properties within the NGSI-LD entity definition\n\n_Properties-of-Properties_ is the NGSI-LD equivalent of metadata (i.e. _\"data about data\"_), it is use to describe\nproperties of the attribute value itself like accuracy, provider, or the units to be used. Some built-in metadata\nattributes already exist and these names are reserved:\n\n-   `createdAt` (type: DateTime): attribute creation date as an ISO 8601 string.\n-   `modifiedAt` (type: DateTime): attribute modification date as an ISO 8601 string.\n\nAdditionally `observedAt`, `datasetId` and `instanceId` may optionally be added in some cases, and `location`,\n`observationSpace` and `operationSpace` have special meaning for Geoproperties.\n\nIn the examples given above, one element of metadata (i.e. a _property-of-a-property_) can be found within the `address`\nattribute. a `verified` flag indicates whether the address has been confirmed. The commonest _property-of-a-property_ is\n`unitCode` which should be used to hold the UN/CEFACT\n[Common Codes](http://wiki.goodrelations-vocabulary.org/Documentation/UN/CEFACT_Common_Codes) for Units of Measurement."},"response":[],"_postman_id":"b503e293-b212-48db-bbb6-b1861793b3bc"},{"name":"Retrieving Context Information","id":"0dd59299-1a8a-4830-bb4d-ddcb86e69550","request":{"method":"GET","header":[],"url":"http://{{orion}}/v2/entities","description":"A consuming application can now request context data by making NGSI-LD HTTP requests to the Orion Context Broker. The\nexisting NGSI-LD interface enables us to make complex queries and filter results and retrieve data with FNQs or with\nshort names.\n\n### Obtain entity data by FNQ Type\n\nThis example returns the data of all `Building` entities within the context data The `type` parameter is mandatory for\nNGSI-LD and is used to filter the response.\n\nThe response returns the Core `@context` by default\n(`https://forge.etsi.org/gitlab/NGSI-LD/NGSI-LD/raw/master/defaultContext/defaultContext.jsonld`) and all attributes are\nexpanded whenever possible.\n\n-   `id`, `type` and `location` are defined in the core context and are not expanded.\n-   `address` has been mapped to `http://schema.org/address`\n-   `name` has been mapped to `http://schema.org/name`\n-   `category` has been mapped to `https://uri.fiware.org/ns/datamodels/category`\n\nNote that if an attribute has not been not associated to an FNQ when the entity was created, the short name will\n**always** be displayed."},"response":[],"_postman_id":"0dd59299-1a8a-4830-bb4d-ddcb86e69550"},{"name":"Obtain Entity Data by id","id":"a7c40a56-c5aa-4bb3-b2d0-c54b99461d1f","request":{"method":"GET","header":[],"body":{"mode":"formdata","formdata":[]},"url":{"raw":"http://{{orion}}/v2/entities/urn:ngsi-ld:Store:001?options=keyValues","protocol":"http","host":["{{orion}}"],"path":["v2","entities","urn:ngsi-ld:Store:001"],"query":[{"key":"options","value":"keyValues","description":"* `keyValues` option in order to get a more compact and brief representation, including just attribute values\n* `values` option combined with a list of attribute values  `attrs`  for an ordered list of attributes only"},{"key":"type","value":"Store","description":"Entity type, to avoid ambiguity in case there are several entities with the same entity id","disabled":true},{"key":"attrs","value":"name","description":"Ordered list of attribute names to display","disabled":true}]},"description":"This example returns the data of `urn:ngsi-ld:Store:001`.\n\nThe response returns the Core `@context` by default\n(`https://forge.etsi.org/gitlab/NGSI-LD/NGSI-LD/raw/master/defaultContext/defaultContext.jsonld`) and all attributes are\nexpanded whenever possible."},"response":[],"_postman_id":"a7c40a56-c5aa-4bb3-b2d0-c54b99461d1f"},{"name":"Obtain Entity Data by type","id":"186559d1-b3bd-4990-a03a-306728b94765","request":{"method":"GET","header":[],"body":{"mode":"formdata","formdata":[]},"url":{"raw":"http://{{orion}}/v2/entities/?type=Store&options=keyValues","protocol":"http","host":["{{orion}}"],"path":["v2","entities",""],"query":[{"key":"type","value":"Store","description":"Entity type, to avoid ambiguity in case there are several entities with the same entity id"},{"key":"options","value":"keyValues","description":"* `keyValues` option in order to get a more compact and brief representation, including just attribute values\n* `values` option combined with a list of attribute values  `attrs`  for an ordered list of attributes only"},{"key":"attrs","value":"name","description":"Ordered list of attribute names to display","disabled":true}]},"description":"If a reference to the supplied data is supplied, it is possible to return short name data and limit responses to a\nspecific `type` of data. For example, the request below returns the data of all `Building` entities within the context\ndata. Use of the `type` parameter limits the response to `Building` entities only, use of the `options=keyValues` query\nparameter reduces the response down to standard JSON-LD.\n\nA [`Link` header](https://www.w3.org/wiki/LinkHeader) must be supplied to associate the short form `type=\"Building\"`\nwith the FNQ `https://uri.fiware.org/ns/datamodels/Building`. The full link header syntax can be seen below:\n\n```text\nLink: <https://schema.lab.fiware.org/ld/fiware-datamodels-context.jsonld>; rel=\"http://www.w3.org/ns/json-ld#context\"; type=\"application/ld+json\n```\n\nThe standard HTTP `Link` header allows metadata (in this case the `@context`) to be passed in without actually touching\nthe resource in question. In the case of NGSI-LD, the metadata is a file of in `application/ld+json` format.\n\nBecause of the use of the `options=keyValues`, the response consists of JSON only without the attribute defintions\n`type=\"Property\"` or any _properties-of-properties_ elements. You can see that `Link` header from the request has been\nused as the `@context` returned in the response."},"response":[],"_postman_id":"186559d1-b3bd-4990-a03a-306728b94765"},{"name":"Filter context data by attribute value","id":"fd1485b5-71e6-4da0-bd5b-b234d4bcd8c3","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Link","value":"<https://schema.lab.fiware.org/ld/context>; rel=\"http://www.w3.org/ns/json-ld#context\"; type=\"application/ld+json\"","type":"text"}],"url":{"raw":"http://{{orion}}/v2/entities/?q=name=='Checkpoint Markt'&type=Store&options=keyValues","protocol":"http","host":["{{orion}}"],"path":["v2","entities",""],"query":[{"key":"q","value":"name=='Checkpoint Markt'"},{"key":"type","value":"Store","description":"Entity type, to avoid ambiguity in case there are several entities with the same entity id"},{"key":"options","value":"keyValues","description":"* `keyValues` option in order to get a more compact and brief representation, including just attribute values\n* `values` option combined with a list of attribute values  `attrs`  for an ordered list of attributes only"},{"description":"Ordered list of attribute names to display","key":"attrs","value":"name","disabled":true}]},"description":"This example returns all `Building` entiies with the `name` attribute _Checkpoint Markt_. Filtering can be done using\nthe `q` parameter - if a string has spaces in it, it can be URL encoded and held within single quote characters `'` =\n`%27`.\n\nThe `Link` header `https://schema.lab.fiware.org/ld/context` holds an array of `@context` as shown:\n\n```json\n{\n    \"@context\": [\n        \"https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context.jsonld\",\n        \"https://schema.lab.fiware.org/ld/fiware-datamodels-context.jsonld\"\n    ]\n}\n```\n\nand therefore includes the FIWARE Building model.\n\nThis means that use of the `Link` header and the `options=keyValues` parameter reduces the response to short form\nJSON-LD as shown below:"},"response":[],"_postman_id":"fd1485b5-71e6-4da0-bd5b-b234d4bcd8c3"},{"name":"Filter context data by comparing the values of an attribute in an Array","id":"83714a3f-566a-46d5-a42c-682925a27f50","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Link","value":"<https://schema.lab.fiware.org/ld/context>; rel=\"http://www.w3.org/ns/json-ld#context\"; type=\"application/ld+json\"","type":"text"}],"url":{"raw":"http://{{orion}}/v2/entities/?q=category==%27commercial%27,%27office%27&type=Building&options=keyValues","protocol":"http","host":["{{orion}}"],"path":["v2","entities",""],"query":[{"key":"q","value":"category==%27commercial%27,%27office%27"},{"key":"type","value":"Building","description":"Entity type, to avoid ambiguity in case there are several entities with the same entity id"},{"key":"options","value":"keyValues","description":"* `keyValues` option in order to get a more compact and brief representation, including just attribute values\n* `values` option combined with a list of attribute values  `attrs`  for an ordered list of attributes only"},{"description":"Ordered list of attribute names to display","key":"attrs","value":"name","disabled":true}]},"description":"Within the standard `Building` model, the `category` attribute refers to an array of strings. This example returns all\n`Building` entities with a `category` attribute which contains either `commercial` or `office` strings. Filtering can be\ndone using the `q` parameter, comma separating the acceptable values.\n\nThe response is returned in JSON-LD format with short form attribute names:"},"response":[],"_postman_id":"83714a3f-566a-46d5-a42c-682925a27f50"},{"name":"Filter context data by sub-attribute value","id":"5a9358e1-f54f-49e1-8115-cf8175552ace","request":{"method":"GET","header":[],"url":{"raw":"http://{{orion}}/v2/entities/?q=address.addressLocality=='Kreuzberg'&type=Store&options=keyValues","protocol":"http","host":["{{orion}}"],"path":["v2","entities",""],"query":[{"key":"q","value":"address.addressLocality=='Kreuzberg'"},{"key":"type","value":"Store","description":"Entity type, to avoid ambiguity in case there are several entities with the same entity id"},{"key":"options","value":"keyValues","description":"* `keyValues` option in order to get a more compact and brief representation, including just attribute values\n* `values` option combined with a list of attribute values  `attrs`  for an ordered list of attributes only"}]},"description":"## Filter context data by comparing the values of an attribute\n\nThis example returns the data of all `Store` entities found in the **Kreuzberg** district of Berlin.\n\nFiltering can be done using the `q` parameter - sub-attributes are annotated using the dot syntax e.g. `address.addressLocality`\n\nBecause of the use of the `options=keyValues`, the response consists of JSON only without the attribute `type` and `metadata` elements."},"response":[],"_postman_id":"5a9358e1-f54f-49e1-8115-cf8175552ace"},{"name":"Filter context data by querying metadata","id":"15f9ad0a-ea73-467a-acf6-10abb6fbe9b1","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":{"raw":"http://{{orion}}/v2/entities/?mq=address.verified==true&type=Store&options=keyValues","protocol":"http","host":["{{orion}}"],"path":["v2","entities",""],"query":[{"key":"mq","value":"address.verified==true"},{"key":"type","value":"Store","description":"Entity type, to avoid ambiguity in case there are several entities with the same entity id"},{"key":"options","value":"keyValues","description":"* `keyValues` option in order to get a more compact and brief representation, including just attribute values\n* `values` option combined with a list of attribute values  `attrs`  for an ordered list of attributes only"}]},"description":"## Filter context data by comparing the values of an metadata attribute\n\nThis example returns the data of all `Store` entities with a verified address.\n\nMetadata queries can be made using the `mq` parameter."},"response":[],"_postman_id":"15f9ad0a-ea73-467a-acf6-10abb6fbe9b1"},{"name":"Filter context data by distance","id":"1823197e-92c7-437f-93d7-35d276b79e86","request":{"method":"GET","header":[],"body":{"mode":"formdata","formdata":[]},"url":{"raw":"http://{{orion}}/v2/entities/?georel=near;maxDistance:1500&geometry=point&coords=52.5162,13.3777&type=Store&options=keyValues","protocol":"http","host":["{{orion}}"],"path":["v2","entities",""],"query":[{"key":"georel","value":"near;maxDistance:1500"},{"key":"geometry","value":"point"},{"key":"coords","value":"52.5162,13.3777"},{"key":"type","value":"Store","description":"Entity type, to avoid ambiguity in case there are several entities with the same entity id"},{"key":"options","value":"keyValues","description":"* `keyValues` option in order to get a more compact and brief representation, including just attribute values\n* `values` option combined with a list of attribute values  `attrs`  for an ordered list of attributes only"},{"key":"attrs","value":"name","description":"Ordered list of attribute names to display","disabled":true}]},"description":"## Filter context data by comparing the values of a geo:point attribute\n\nThis example returns the data of all `Store` entities found within 1.5km the **Brandenburg Gate**  in **Berlin** (*52.5162N 13.3777W*)"},"response":[],"_postman_id":"1823197e-92c7-437f-93d7-35d276b79e86"}],"event":[{"listen":"prerequest","script":{"id":"581cc060-de73-4283-915a-fcaa1c126830","type":"text/javascript","exec":[""]}},{"listen":"test","script":{"id":"5215414e-418f-4c32-8070-b68d62c90ea4","type":"text/javascript","exec":[""]}}],"variable":[{"id":"df0c7c83-8325-4d8f-8b3f-bea47630872d","key":"orion","value":"localhost:1026","type":"string"}]}