API real time

How to use API

The API of Muoversi a Roma are made available through webservice XML-RPC (with support to the voided values - NIL -).

NB Make sure to have activated the support of the voided values in bookstore XML-RPC in use.

In order to access the services a developer's key is necessary. Visit the following page:

Your developer's key

It will be asked of you to identify yourself or to register as a user of Roma Servizi per la Mobilità.

The URL of the web service has a structure of this type:
http://muovi.roma.it/ws/xml/<nome_servizio>/<versione>

As an example the URL of the authentication service is:

http://muovi.roma.it/ws/xml/autenticazione/1

In order to use the webservice it is necessary to identify yourself. In this way it is necessary to use the method Login of the authentication service, passing through the following parameters:

  • developers_key. It is the key for the access to the web-service supplied at the moment of the registration as a developer
  • user_id. In case your application allows you to univocally identify every customer (as an example through an id placed on the device of the customer through a cookie), we ask you to please provide the id of the generated customer. In other words, every time a customer approaches the system it will be necessary an invocation of the method Login; the token of authentication given back from the method Login will be then used for all the successive invocations of web-service that you will carry out in order to supply data to the customer in issue. If, instead, it is not possible to identify the customers, it is sufficient to pass the empty string as value of the user_id's parameter.

In case of success, the method gives back a token of session to use for the invocation of the other webservice. In absence of authentication all the web-services will give back the error code 824 (XRE_NOT_LOGGED).

Example

Consult an example of the use of API in Python.

Conditions of use

The webservices of Muoversi a Roma are offered without any guarantee, and with one policy of fair usage. Pattern of improper use will be able to involve the suspension or the definitive stop of the developer's key.

The data distributed from the webservice are supplied with the licence CC BY 3.0 IT.

Structure of the answer

All the methods, with the exception of authentication Login, give back a dictionary with the following keys:

  • id_request: associated univocal identification to the demand (string).
  • answer: answer of the method, documented in the continuation.

Directory of the services available

Authentication

Cerca Percorso

  • percorso.Cerca - It executes the geocoding of the starting and arriving addresses, calculating a route; it gives back the result both in textual format and as a map.

Journey Planner

  • paline.Previsioni - It gives back the forecasts of arrival to the bus stop, organized like in the website muovi.roma.it.
  • paline.Percorsi - It gives back the directory of the routes of the line, and informs if the line is open to the service
  • paline.Fermate - It gives back the directory of stops of the route with the code id_route. Deprecate: use the method bus stops.Route
  • paline.Percorso - It gives back information about the route: the stops, the vehicles, the speeds of arch, the timetables of departure from the last stop, etc
  • paline.PalinaLinee -  It gives back the directory of the lines that move for the bus stop, with the relative information (monitoring, qualified)
  • paline.Veicolo - It gives back information on the vehicle that is covering the route: generic information on the vehicle, stops and the forecasts of arrival to the stops
  • paline.SmartSearch - It carries out a search of paline stops and lines based on a string of search

Private transportation

  • ztl.Lista - it gives back the list of the existing LTZ (Limited Traffic Zone)
  • ztl.Orari - It gives back the timetable of the beginning, the timetable of the end and the state of activation of all LTZ for a certain day.
  • ztl.Modifiche.PerZtl - It gives back the list of the extraordinary modifications for a certain LTZ
  • ztl.Calendario - It gives back the programmed calendar of the current week for a LTZ, without considering the extraordinary modifications
  • tempi.ListaTratte - It gives back the directory of the drafts, each one with relative last time of relevant distance.
  • tempi.TempiTratta - It gives back the times of distance of one segment found in the last hour
  • tempi.ListaItinerari -  it gives back the directory of the itinerary; for every itinerary the directory of the segment, each with its relative last time of its found distance