Skip to content

EMBERS Developer Docs

Getting Started

Welcome! You’ve reached the Open Data Day Hackathon Documentation by EMBERS.

If you’re here, congrats, you’re a step closer to build something great for your fellow Cologne citizens. We give you all the tools you need to build your app. EMBERS offers different APIs related to mobility for you to start developing your idea. During the Open Data Day Hackathon EMBERS will open up some parts of its API for you to use, namely:

  • The Northbound Broker that gives you real-time information from the data sources available and your own devices;
  • The Southbound Broker which gives you the possibility of publishing your own data;
  • The Routing Engine which allows you to calculate the best routes given the type of vehicle you are using.

We've talked about giving access to data sources, didn't we? All right, these are the data APIs with data for you to consume, in real-time:

  • Routing - Route planning between two locations using multiple means of transportation (by car, bicycle, on foot and multi-modal transportation);
  • Bicycle - Real-time positioning of bicycles and availability of bike-sharing docks;
  • Air Quality - Real-time information about AQI, Carbon Monoxide, Humidity, PM10, Pressure, Sulfur Dioxide, PM25, Ozone, Nitrogen Dioxide and Temperature is the available air quality data (observations) we are collecting;
  • Issue Reporting - Real-time information about the reporting service used by citizens.

Being EMBERS an IoT platform for urban mobility, there's also room for data from your own devices, and we'll teach you how to integrate your devices and publish your datasets.

Let’s dive right in! It gets highly technical from here on out, so, beware non-coders :)

And remember, if you need any help, feel free to join our Slack Team and talk to us directly!

Slack


First things first: create an account

The first step to access the EMBERS infrastructure is to create an account, so you can generate API keys and implement your app.

For that, you'll need to follow these simple steps:

  1. Go to the Developer Dashboard
  2. Click on the Create Account button
  3. Fill in the form presented
  4. Click Register

Woohoo, the first step is complete!


Today's specials: EMBERS APIs

All the data is accessible via RESTful APIs. To get it, you'll need a special token, a parameter that goes within your HTTP requests and allows us to ensure you can actually access the data.

Get yourself an API Key

The process of how to get the tokens can be found below.

  1. Access the Developer Dashboard
  2. Make sure you've already created an account, if not, please refer to that step
  3. Login with your account
  4. Go to your profile and click on Click here to generate your access token
  5. Your access token has been generated and is ready to be used!

HINT: You can use your access token the amount of times you wish. If you feel it might have been compromised, you can always access the Developer Dashboard and refresh it (i.e. turn it obsolete replacing by a new one).

How to use the API Token

You should use the provided API Token everytime you need to access an API. To use it you need to add an Authorization Header to your request. This header needs to follow this example: Authorization: Token <your_token_here>.

Check out the following curl command to have a real example:

curl --request GET \
  --url 'https://data.embers.city/v2/entities?type=AirQualityObserved' \ 
  --header 'Authorization: Token <your_token_here>'

How to fetch data

The API is accessible via https://data.embers.city/v2/. This is an instance of the FIWARE Orion Context Broker and serves as a real-time messaging API.

This endpoint lets you check the current state of a sensor. The available types are: - Vehicle, for the real-time positioning of the bicycles; - AirQualityObserved for the real-time Air Quality in Cologne; - ParkingGroup for the position of the bicycle stations; - IssueReport for the reports that the citizens have made; - device_<device_uuid> for the devices you've created.

The following curl command is a sample of how to get the current Air Quality observations for the city of Cologne:

curl --request GET \
  --url 'https://data.embers.city/v2/entities?type=AirQualityObserved' \ 
  --header 'Authorization: Token <your_token_here>'

During the Open Data Day, there will be a special event type, which represents the devices created by you. These can be identified/fetched via the concatenation of the string device and the device_uuid you've generated in the Developer Dashboard!

A complete curl command to illustrate this is the following:

curl --request GET \
  --url 'https://data.embers.city/v2/entities?type=device_<your_device_uuid>' \ 
  --header 'Authorization: Token <your_token_here>'

Did it work?

Hackerman

HINT: To know more about the API we are using (filters, options, etc.) please go to this link. To ease things we are only using the entities and subscriptions endpoints, so don't get lost in the rest of the documentation!

HINT: In the AirQualityObserved events, please be aware that sometimes the coordinates swap the latitude with the longitude! We tried hard to solve this problem, but this is an issue with the source! :)


How to publish your own data

Even when you have at your disposal many datasets from the city, you might want to integrate your own data, from your hardcore IoT device(s).

For that, EMBERS provides you with an API to publish data. You just need to follow some basic steps:

  1. Make sure you've already created an account, if not, please refer to that step
  2. Log into the Developer Dashboard
  3. Click the Add button on the devices
  4. On the next menu, give a name to your device and click Save
  5. You should be redirected to the list of devices linked to your account

After this, you have a device created in the system, which is now capable of sending messages through the platform.

To publish data, you need to send an HTTP POST message to the https://msg.embers.city/messages endpoint.

  • The HTTP POST message should contain the following headers (replacing the template with your device's credentials):
    • meshblu_auth_uuid: <uuid created in the dashboard>
    • meshblu_auth_token: <token created in the dashboard>
  • In the body of the POST message, you should always pass the following body:
{
    "devices": "38bc5410-3f26-4d05-ae60-ff21fae77e87",
    "payload":{
        "Key": "Value",
        "Key1": "Value1"
    }
}
  • You always need to send the "devices": 38bc5410-3f26-4d05-ae60-ff21fae77e87" for the messages to be accepted by the platform!
  • After this, you should receive from the API an HTTP response with 204 as status code.

Find below a sample curl command on how to send a message:

curl --request POST \
  --url https://msg.embers.city/messages \
  --header 'content-type: application/json' \
  --header 'meshblu_auth_uuid: <your_device_uuid>' \
  --header 'meshblu_auth_token: <your_device_token>' \
  --data '{
  "devices": "38bc5410-3f26-4d05-ae60-ff21fae77e87",
  "payload":{
        "key": "Value",
        "key1": "Value1"
  }
}'

The payload is a JSON dictionary which should contain the specific attributes your IoT device measures, such as, for example, CO2 level, Temperature, etc.

This HTTP POST is easily replicable using apps like Postman or Insomnia.

Now that you are capable of publishing data into the platform, you must want to see how you can access it to integrate it with your awesome application!

To do that, you only need to follow these simple steps:

  1. Use the northbound API located at https://data.embers.city/v2/entities
  2. Complete the request with https://data.embers.city/v2/entities?type=device_<your_device_uuid> to filter only for your specific device
  3. Don't forget to use your token to get authorized on the API: just pass the Authorization Header with the content Token <your_access_token>. If you don't have one, please refer to that step.

You should see the current context for your entity! This will only show the latest update.

If you want to receive this data in real-time, without having to poll, jump to the next section where we discuss how to subscribe to this context and get real-time updates in your app!


Subscribe to Real-time Events

Our API offers a publish-subscribe mechanism, where you can receive real-time updates on specific context information, where the platform will send you a POST request to any given URL or IP you provide.

Please note that this URL or IP must be public.

To set up a simple public server, you can use ngrok. With this tool, you can run a service on any port and have it connected to a public URL, which you can then use in the reference attribute, so you can receive the POST requests. Below is an example of the request body to send:

curl --request POST \
  --url https://data.embers.city/v2/subscriptions/ \
  --header 'authorization: Token <your_access_token>' \
  --header 'content-type: application/json' \
  --data '{
  "description": "Test device subscribe",
  "subject": {
    "entities": [
      {
        "idPattern": ".*",
        "type": "device_<your_device_uuid>"
      }
    ]
  },
  "notification": {
    "http": {
      "url": "<your_public_ip>"
    },
    "attrsFormat": "keyValues"
  },
  "expires": "2117-05-01T14:00:00.00Z"
}'

This subscription will notify you on the reference endpoint (url) you've provided, each time there is an update on your device.

Please keep in mind that it will only publish the attributes you've selected when doing the subscription.

The type and idPattern are mandatory and relate to the type of entity you are subscribing, on the example we are subscribing to get all the attributes (with a regular expression .*) of a specific device you've added (device_<your_device_uuid>).

Easy, peasy.


Don't get lost: use our route planning service

With this API, you can get the best route to your destination!

Best routes

In this chapter you will find a service to never get lost! You can even plan routes with different transportation modes!

To use the API you should call https://routing-api.embers.city/. A detailed example of an API call is as follows:

https://routing-api.embers.city/api/routing/?fromPlace=50.93633658100821,6.976017951965332&toPlace=50.944557395196654,6.938767433166504&mode=TRANSIT,WALK&maxWalkDistance=1000&date=20180227&time=18:21&arriveBy=false

You can filter the request with these parameters:

  • fromPlace: The starting point of your route, accepts coordinates in the form of latitude,longitude;
  • toPlace: The finishing point of your route, accepts coordinates in the form of latitude,longitude;
  • mode: The transportation modes you wish to use in your route. You can join the two of them to have a route calculated with more than one transportation means, for example TRANSIT,WALK. The accepted modes are the following:

    • WALK for walking only;
    • TRANSIT for public transportation only;
    • CAR for private cars;
    • BICYCLE for bicycle routes.
  • maxWalkDistance: The maximum distance you wish to walk, in meters.

  • date: The date in which you wish to plan the route, for example 2018-02-27 (other formats are accepted but this one is our favourite!);
  • time: The time in which you wish to plan the route, for example 18:21 (should be the same timezone as the public transportation agencies, in this case Europe/Berlin - CET);
  • arriveBy: When true, it assumes the date and time you had passed as the arrival date and time. When false (default), it uses them for the departure timing.

The response will give you the different iteneraries found and the step by step navigations to your destination.

  • requestParameters: Returns the parameters you had sent;
  • plan: Returns your planned journey, from which you should focus on:
    • itineraries: Your set of three itineraries (at most), each divided in legs;
      • legs: The navigation steps of your itinerary, which have an encoded polyline to be drawn on a map;
      • instructions: The turn-by-turn navigation instructions to be used during the trip;
      • mode: The type of transportation you will use in that step of the trip.

HINT: Our routing planner assumes the timezone of the local public transportation agencies (Europe/Berlin, hence CET) when doing the trip planning calculations!

However, the responses are UTC by default so please bear in mind that you'll need to "fix" them in your client app (for instance, the example above requests a trip at 18h21 and the response - after converting it from Unix milliseconds, of course - is 17h21).

Heh, it's not a bug, it's a feature! :)


Last but not least: have fun!

We truly hope you can build something awesome, and have some fun!

Best day ever!

And remember, if you need any help, feel free to join our Slack Team and let us know if you find any issue, bug, or need any help with the APIs, we'll be happy to help!