KIRI API v2

Pascal edited this page Aug 8, 2017 · 2 revisions

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://kiri.travel/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:

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://kiri.travel/images/means/angkot/baloon/cicaheumledeng.png

Image of Cicaheum Ledeng Angkot

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://kiri.travel. 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://kiri.travel?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.

Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.