Furkot provides Rest API to access user trip data. Using Furkot API an application can list user trips and display stops for a specific trip. Furkot API uses OAuth2 protocol to authorize applications to access data on behalf of users.

Furkot API supports following operations:

• Get user's list of trips

• Get stops of a specified trip

Formal definition of Furkot API in Open API specification format (a.k.a. swagger) can be found here.

Registration ¶

Start by registering online to obtain your unique partner identifier. Email us to acquire Furkot API credentials for your application.

Your email should contain:

1. your partner identifier,

2. a link to your application,

3. the application name that you want us present to users,

4. one or more redirect URL(s) to be used during the OAuth2 authentication flow.

If your application is not live yet, send us a short description including, if possible, some screenshots and the planned release date. After your application is released send us the link.

If you plan to use Furkot API in a paid application, we ask that you grant us free access to the full-featured version of your application for as long as you intend to use Furkot API (access to a time-limited trial version is not sufficient).

Endpoint ¶

Furkot Rest API can be accessed from following endpoint:

https://trips.furkot.com/pub/api

Please note that all API requests need to be sent over HTTPS so that trip information is protected during transfer and access tokens are not compromised.

Authorization ¶

Furkot API uses the OAuth2 protocol to authorize applications to access data on behalf of its users. Write to us to obtain a client ID and a client secret for your application.

Authorize web server application ¶

You need both client ID and client secret to obtain access token to be used on a server. Your registered redirect URL has to use the HTTPS protocol.

1. Direct users to:

    https://trips.furkot.com/oauth/authorize
      ?client_id=<your client id>
      &redirect_uri=<your registered redirect URL>
   

2. Furkot's OAuth 2.0 server will authenticate the user and obtain their consent to access user's trips in your application. The response will be sent back to your application using the redirect URL you registered with a query parameter code set to the authorization code:

    <your registered redirect URL>
      ?code=<authorization code>
   

3. Exchange the authorization code for an access token:

    https://trips.furkot.com/pub/api/access_token
      ?client_id=<your client id>
      &client_secret=<your client secret>
      &code=<authorization code>
      &grant_type=authorization_code
      &redirect_uri=<your registered redirect URL>
   

4. The response will be a JSON object with a following field:

• access_token - value of the access token

Authorize web client or mobile application ¶

You only need client ID to obtain access token for your mobile app or a web client app.

1. Direct users to:

    https://trips.furkot.com/oauth/authorize
      ?response_type=token
      &client_id=<your client id>
      &redirect_uri=<your registered redirect URL>
   

2. Furkot's OAuth 2.0 server will authenticate the user and obtain their consent to access user's trips in your application. The access_token will be sent back to your application using the redirect URL you registered with a hash value set to the access token:

    <your registered redirect URL>#access_token=<access token>
   

Authenticate requests ¶

To authenticate API calls attach the received access token to all Furkot API requests. Furkot will accept either bearer token authentication or access_token query parameter. Bearer token authentication requires adding Authorization header value of which contains the word Bearer followed by a space and the access token.

Bearer token example:

curl https://trips.furkot.com/pub/api/ping -H "Authorization: Bearer <access token>"

Query parameter example:

curl https://trips.furkot.com/pub/api/ping?access_token=<access token>

Requests ¶

Furkot API supports following requests:

• list of user trips: /pub/api/trip

• list of a trip stops: /pub/api/trip/<trip id>/stop

• list of a trip skipped stops: /pub/api/trip/<trip id>/skipped

• test only: /pub/api/ping

Common parameters ¶

Every Furkot API request requires either access_token parameter or Authorization header.

List of trips ¶

Once authenticated your application can use HTTP GET to obtain the list of user's trips:

/pub/api/trip

The request returns a JSON array of objects with following fields:

• id - trip id
• name - name of the trip
• description - description of the trip (truncated to 200 characters)
• begin - begin of the trip in its local timezone as YYYY-MM-DDThh:mm
• end - end of the trip in its local timezone as YYYY-MM-DDThh:mm

Trip stops ¶

Details of each trip can be obtained by HTTP GET request:

/pub/api/trip/<trip id>/stop

The request returns a JSON array of objects with following fields:

• name - name of the stop
• address - address of the stop
• arrival - arrival at the stop in its local timezone as YYYY-MM-DDThh:mm
• departure - departure from the stop in its local timezone as YYYY-MM-DDThh:mm
• nights - number of nights
• coordinates - geographical coordinates of the stop
• route - route leading to the stop
• url - url of the page with more information about the stop
• passthru - Boolean field set to true for pass-through points anchoring route

Geographical coordinates have following fields:

• lat - latitude
• lon - longitude

Route leading to the stop has the following fields:

• mode - travel mode: car, motorcycle, rv, bicycle, walk, ferry, flight, other
• polyline - route path compatible with Google polyline encoding algorithm
• duration - route duration in seconds
• distance - route distance in meters

If your application is using Google Maps JavaScript API, use function google.maps.geometry.encoding.decodePath to decode polyline for the route. There are also compatible implementations of the algorithm available, for instance jieter/Leaflet.encoded or mapbox/polyline.

Trip skipped stops ¶

List of skipped stops and routes for each trip can be obtained by HTTP GET request:

/pub/api/trip/<trip id>/skipped

The request returns a JSON array of objects with following fields:

• name - name of the stop
• address - address of the stop
• coordinates - geographical coordinates of the stop
• route - route leading to the stop - only present for skipped routes
• url - url of the page with more information about the stop