ABOUT CITOPIA API

Citopia is a blockchain powered mobility marketplace app. This has been provided for developers to use as a platform for their MOBI Grand Challenge Phase II solution. However, the use of Citopia is NOT required in order to enter a submission.

Citopia provides the following two core features:

  • Travel | from point A (can be a user’s current location) to point B. Point B is optional and can be any arbitrary place where a trip finishes. This feature stands for mobility and payments. We call this feature a trip.
  • Locations | places on the map where user can spend his credits. This feature stands for services and payments.

Citopia has following four core roles:

  • User (regular people, Citopia app users)
  • Local business (“Business”)
  • Third-party service (“Provider”)
  • City

Providers provide value for mobility, services and payments while businesses only for the services and payments. Providers also must provide an API that Citopia will use to communicate with providers in real time. City manages high level processes while users are customers who use the Citopia app in which credits can be earned and spent.

Businesses and providers will self register via our web app.

PROVIDER

To initiate the Citopia app with a provider, a provider will self register via Citopia web app. Registration pushes the provider into a live state meaning Citopia will actively route requests to the provider. Once a provider has gone through registration, Citopia app will call its API methods to get the list of available “services” and “bits”.

There are several types of services a provider can provide:

Type A (example: User Walks from PointA to PointB)

When citopia app user selects walking / driving his own car / riding his bicycle he selects this service and starts his trip by pressing “start.” We register trip and trip continues until user completes the trip.

Flow:

  • App requests for all services available for a current / selected location (/services-availability/) and we show all services returned success status in the list for trip
  • User clicks “start” and we register the trip (/trip-register/)
  • While the trip is in progress we constantly (based on a frequency defined by a provider) send information about the user's current location. We also constantly query trip information (/trip-info/). Trip continues until service returns a “completed” trip status or app user decides to manually complete the trip
  • When trip has finished Citopia suggests user to pay using app (if it was a paid service). If user has paid we send information back to our servers
  • At the end app shows a user information about spent/earned credits

Type B (example: User Utilizes Bikeshare from PointA to PointB)

When Citopia app user selects bikeshare provider he / she sees all available bikes in his / her general proximity. He / she can select any bike and move from his current location pointA to some pointB.

Flow:

  • App requests for all services available for a current / selected location (/services-availability/) and we show all services returned success status in the list for trip
  • User selects particular service and we send a second request to get all the bits we need to show on the map (/service-info/). For example we show all bikes around user.
  • User selects a bike and app asks to scan a QR code on the bike. One he / she scan the bike code we register our trip (/trip-register/)
  • While the trip is in progress we constantly query trip information (/trip-info/). Trip continues until service will return “finished” trip status or app user finishes trip on his own
  • When trip has finished Citopia suggests user to pay using app (if it was a paid service). If user has paid we send information back to our servers
  • At the end app shows a user information about spent/earned credits

Type C (example: User Utilizes Rideshare service from PointA to PointB)

When Citopia app user selects two points on the map (A and B) and he / she wants to initiate a trip, providers are able to list their services to be used for this trip. For example, user wants to go from A to B using RideshareAcme where RideshareAcme is a service provider. We list RideshareAcme’s services in the lists and user can select RideshareAcme service for his trip and organize further processes.

Flow:

  • App requests for all services available for a given trip (/services-availability/) and we show all services returned success status in the list for trip
  • User selects particular service and we send a second request to get all the bits we need to show on the map (/service-info/)
  • User clicks “start trip” and we tell provider about new trip started and we get back a new map bits that we need to show on the map to reflect trip start changes (for example a single car left for a ride and this needs to be shown), it also sends status information back (for example “Car X is going to pick up you”) (/trip-register/)
  • While the trip is in progress we constantly query trip information (/trip-info/). Trip continues until service will return “completed” trip status or user manually completes trip
  • When trip has finished Citopia suggests user to pay using app (if it was a paid service). If user has paid we send information back to our servers
  • At the end app shows a user information about spent/earned credits

Type D

While you are on the trip Citopia suggests different services when he / she gets close to the area served by providerFor example, when a user is commuting home, and a toll bridge is in route - Citopia will suggest toll be paid via Citopia. Another example is parking - if user gets close to his destination Citopia will suggest nearby parking availability with payment option via Citopia.

Flow:

  • While on a trip we send current coordinates to all providers to get a listing of suggested services ( a check takes place if services are provided in this area and return list of suggestions ). PointB will also be sent to all providers to ascertain if trip is beginning or ending (example - parking) (/trip-service-suggestions/)
  • If user selects and utilizes the service(s) - he / she can pay via Citopia

App API

API documentation is available here on github.

GLOSSARY 

  • Provider
    Is a 3rd-party service provider.
  • Business
    Local businesses participate in a Citopia app, where user can spend his credits.
  • Service
    Is a service provided by a 3rd-party service provider.
  • Trip
    Is a single mobility action from point A to B by Citopia app user.
  • Bit
    Is a single item on the Citopia map that user sees. For example, it can be an rideshare car, parking space, rental bike, bridge toll or restaurant.
  • Map Bit
    Is a single instance of the Bit currently located on the map