The Policy API
The policy api, what is it ? How to integrate ?
Why Use the Policy API?
One of the key features of the Mobility Data Specification is the ability to share information to Operators about the policies the city wants to see implemented. The "Policy API" is designed to share the rules of the road with operators (and the general public) so that there is a shared definition of how many devices are permitted to operate, where are allowed to be parked and ridden, and where trips may require extra fees (or receive subsidies).
"Sharing the Policy API" is the process of the City (or Vianova, on the City's behalf) providing information in the "regulation" page of Cityscope to the operators. This information comes to the operators through an API on Vianova's developer portal. Operators "query" the API (request data from it) and receive a map of what policies are in effect. Any time a change is made in the regulation page (for example, a new No Parking Zone), the data will be transmitted to the operators, who will update their apps and devices accordingly.
Cities and operators, working together, have to determine what a "violation" of a policy represents. In some cases, as a condition of their permit or tender, an operator can be fined for violating a policy. In other cases, policies may be seen as a city's preferred outcomes, but there are no penalties for non-compliance. Cities and operators should also establish a shared understanding of how quickly a change in the City's policy should be integrated into the operators' devices and apps, as this process still frequently involves manual updates.
In any case, it is highly encouraged that cities share access to the API (or instruct Vianova to provide access). When cities provide information about policy zones through pdfs or descriptions, the way that those zones are drawn by operators can be slightly different, as seen in the example below in a Swedish city:
Having a standard definition of these policies supports better compliance in policy zones, even if the city is not formally enforcing them. As GPS accuracy improves, policies will serve as an ever more powerful tool for managing the curb.
Policy API Integration
The Policy API is efficient way for cities to describe any physical sets of rules from the PROW into a machine readable format, for the benefits of :
- fast integration
- specified at the OMF level
- JSON readable
- Instant availability of new rules
- Immutability of rules and policies
Machine readable
If you are a programmer and would like to integrate our API, it's quite straight forward :
You can access all regulations for a single city by reading this HTTP endpoint :
https://policies.vianova.io/mds/VERSION/ORG/CITY/policy/policies/
Replace VERSION by the wanted MDS version number, we currently support:
Replace CITY by your city name, replace ORG by your org name, ex:
https://policies.vianova.io/mds/1.1.0/London/London/policy/policies/
London
Human readable
We also understand it can be complicated to write and read code, especially if it is not your technical domain. For a more readable experience, please proceed exactly as you would for Machine readable but add the extra URL parameter "format=geojson", ex :
https://policies.vianova.io/mds/1.1.0/London/policy/policies?format=geojson
This URL will gives you a flat file with all the policies/rules detail and also a human readable sentence auto-generated, here is an example :
Policy \"MaxFS - TENDER - TP1\" (98a859c2-6f87-4fc1-bbdd-2ad54053f970) starting from 2021-03-31 and ending at 2021-04-29 states that for vehicle types (scooter) at most 550 devices in states (reserved, available) for days (mon, tue, wed, thu, fri, sat, sun) are authorized in zones 98a859c2-6f87-4fc1-bbdd-2ad54053f970.
Useful tips
You can copy/paste or import this file in any GeoJSON readable tool, ex :
[https://geojson.io ](http://google.com
Videos and Additional Resources
Updated over 2 years ago