Availability of a Ridepooling Service

Availability of a Ridepooling Service#

To offer a Ridepooling Service to our Customers, we first need to understand in which regional areas and at what times a Ridepooling Service is available. To achieve this, we query the Service Areas that have been assigned to us and their respective Service Hours.

Regional Availability#

List All Service Areas#

To get a list of all Service Areas available to us, we use the ListServiceAreas RPC.

grpcurl \
  -H "authorization: Bearer ${ACCESS_TOKEN}" \
  -import-path ./protos/ \
  -proto "moia/ridepooling/servicearea/v1beta2/servicearea.proto" \
  ridepooling-api.int.eu-central-1.moia-group.io:443 moia.ridepooling.servicearea.v1beta2.ServiceAreaService/ListServiceAreas

We receive a response of type ListServiceAreasResponse, which contains a list of ServiceAreas, and an optional nextPageToken to support pagination.

If a nextPageToken is present, it can be used to retrieve subsequent Service Areas by passing it as pageToken in a ListServiceAreasRequest.

If nextPageToken is not present, there are no more Service Areas to return.

Once we have our list of Service Areas, we can use an id to retrieve a single Service Area.

Get Single Service Area#

If we are only interested in the details of one Service Area we can instead use the GetServiceArea RPC and provide the id in the request body. The following example details a GetServiceAreaRequest. We replace $SERVICE_AREA_ID with the id of the Service Area we are interested in.

# export SERVICE_AREA_ID="<replace_with_your_service_area_id>

grpcurl \
  -H "authorization: Bearer ${ACCESS_TOKEN}" \
  -import-path ./protos/ \
  -proto "moia/ridepooling/servicearea/v1beta2/servicearea.proto" \
  -d "{\"id\": \"$SERVICE_AREA_ID\"}" \
  ridepooling-api.int.eu-central-1.moia-group.io:443 moia.ridepooling.servicearea.v1beta2.ServiceAreaService/GetServiceArea

We receive a response of type GetServiceAreaResponse which contains a ServiceArea.

Information Displayed in a Service Area#

A single entity of a Service Area contains formal and geographical information. Formal information includes a name, id, create_time and modify_time. Geographical information includes a polygon, time_zone and country describing the region in detail.

Here, the polygon defines a closed geographical area. It consists of a list of latitude and longitude coordinates (vertices) with the first and last vertice being the same. This location polygon can be visualized using a Map provider such as Google, HERE or Bing.

Exemplary Polygon in Hamburg — Visualization of an exemplary Polygon in Hamburg#

Temporal Availability#

A Service Area has multiple Service Hours, which are time intervals that define the times in which Ridepooling is offered in the respective Service Area. Service Hours are defined for the next years, ordered chronologically from the current time to the future.

To get a list of all Service Hours available for a specific Service Area, we use the ListServiceHours RPC. We replace $SERVICE_AREA_ID in the request with the id of the service area we are interested in.

grpcurl \
  -H "authorization: Bearer ${ACCESS_TOKEN}" \
  -import-path ./protos/ \
  -proto "moia/ridepooling/servicearea/v1beta2/servicearea.proto" \
  -d "{\"service_area_id\": \"$SERVICE_AREA_ID\"}" \
  ridepooling-api.int.eu-central-1.moia-group.io:443 moia.ridepooling.servicearea.v1beta2.ServiceAreaService/ListServiceHours

We receive a response of type ListServiceHoursResponse, which contains a list of TimeIntervals, and an optional nextPageToken to support pagination. If a nextPageToken is present, it can be used to retrieve subsequent Service Hour Intervals by passing it as pageToken in a ListServiceHoursRequest. If nextPageToken is not present, there are no more Service Hour Intervals to return. We can end the repeated calls prematurely if we have already received all the Service Hour Intervals for the relevant period.