KIRI API v2

Introduction

KIRI API can be accessed in several ways, described in the following subsections. All requests must contain API key, which can be retrieved through the KIRI API Management Dashboard.

API Specifications

Web Service

All web service requests should be sent as GET request to https://projectkiri.id/api (Note in previous versions of API, it's possible to request using POST and/or to different URL. However, such methods are now considered obsolete.)

Parameters are passed in the GET parameters, with the mandatory parameter being mode parameter, to determine which service is requested. This parameter and the rest will be explained in the following subsections.

Returned values are formatted in JSON, with guarantee of minimum two variables:

Variable	Possible values	Description
status	ok or error	Determines whether the request was performed successfully or not.
message	Text string (exists when status is error)	Explains the specific cause of the error.

Most requests requires API key that can be generated in the KIRI API Management Dashboard.

Routing Web Service

To perform routing request, you need to provide the following parameters:

Parameter	Valid values	Description
version	2	Tell service to use version 2 protocol
mode	findroute	Instruct service to find the route
locale	en or id	The language to be used for response
start	lat,lng (both are decimal values)	Latitude and longitude of the start point
finish	lat,lng (both are decimal values)	Latitude and longitude of the finish point
presentation	desktop	For backward compatibility only
apikey	16-digit hexadecimals	Your API key

The KIRI API service responds with the following format:

{
	"status": "ok" or "error"
	"routingresults": [
		{
			"steps": [
				[
					"walk" or "none" or others,
					"walk" or vehicle_id or "none",
					["lat_1,lon_1", "lan_2,lon_2", ... "lat_n,lon_n"],
					"human readable description, dependent on locale",
					URL for ticket booking or null,
					URL for route editor or null,
				],
				[
					"walk" or "none" or others,
					"walk" or vehicle_id or "none",
					["lat_1,lon_1", "lan_2,lon_2", ... "lat_n,lon_n"],
					"human readable description, dependent on locale",
					URL for ticket booking or null,
					URL for route editor or null,
				]
			],
			"traveltime": any text string, null if and only if route is not found.
		},
		{
			"steps": [ ... ],
			"traveltime": "..."
		},
		{
			"steps": [ ... ],
			"traveltime": "..."
		},
		...		
	]
}

When findroute request is successful, the server will also return the routing result, which is an array of steps, each containing the description in the format of another array:

• Index 0 contains the means, either "walk", "none" (route not found), or others for vehicle
• Index 1 contains the means detail:
  • If the means was "walk", then this field must be "walk"
  • If the means was "none", then this field must be "none"
  • Otherwise, then this field contains the vehicle id, which can be used to decide which picture to show .
• Index 2 is another array of string, containing the path in "lat,lon" format. When the means is "none", it contains exactly two elements, that is the start and finish point.
• Index 3 is the human readable form of those information, to be shown to the user. This field is dependant on the locale parameter provided at the request. This information may contain the following token:
  • %fromicon = a placeholder for showing the "from" icon, especially in mobile mode presentation
  • %toicon = a placeholder for showing the "to" icon, especially in mobile mode presentation
• Index 4 contains the URL for ticket booking, if available. Otherwise it would be null.
• Index 5 contains the URL for route editor, if available. Otherwise it would be null.

Note that KIRI provides three types of image bank that can be accessed through the following URL:

• https://projectkiri.id/images/means/[means]/[means_details].png
• https://projectkiri.id/images/means/[means]/baloon/[means_details].png

Where [means] can retrieved from index 0 of return value, and [means_details] can be retrieved from index 1. For example, here's the URL for baloon image of angkot cicaheumledeng: https://projectkiri.id/images/means/angkot/baloon/cicaheumledeng.png

Search Place Web Service

The "Routing Web Service" finds the route based upon lat,lng coordinate, which is inconvenient for end users. This service helps to "convert" text string to lat,lng. Note that this request is usually passed again to a third party provider. However using this service guarantees the same result as it is in https://projectkiri.id. To perform routing request, you need to provide the following parameters:

Parameter	Valid values	Description
version	2	Tell the server to use protocol version 2
mode	searchplace	Instruct service to perform place search.
region	cgk, bdo, mlg, or sub	lowercased IATA Airport Code of the city to search places
querystring	any text string at least 1 character	The query string to be searched using the service. It may be appended with ", " to alter the region.
apikey	16-digit hexadecimals	Your API key

When findroute request is successful, the server must also return the routing result, which is an array of steps, each containing the description in the format of another array:

{
	"status": "ok" or "error"
	"searchresult": [
		{
			"placename": "place name"
			"location": "lat,lon"
		},
		{
			"placename": "place name"
			"location": "lat,lon"
		},
		...
	]
	"attributions": [
		"attribution_1", "attribution_2", ...
	]
}

When findplace request is successful, the server must also return the placeresult, which is an array of steps, each containing the description in the format of mapping:

• searchresult -> contains array of result objects:
  • placename: the place name
  • location: latitude, longitude of the place
• attributions -> contains array of string, additional attribution to show

URL Linking “Smart Direction”

Smart Direction works simply by asking the user’s browser to navigate to certain URL. The URL to navigate is as follow: https://projectkiri.id?start=start&finish=finish&locale=locale

The parameters are explained below:

Parameter	Valid values	Description
start	Query string or lat,lng	Text query of a place to search or latitude,longitude (in decimal) as start point
finish	Query string or lat,lng	Text query of a place to search or latitude,longitude (in decimal) as finish point
locale (optional)	en or id	Forcing the user preference locale (language).

This API is free to use, and API key is not required.