Countries

The countries resource can be used to list the countries where BimBimBikes connected rental companies are located. The endpoint URL for this resource is:

GET - /countries/

The response contains a list of all countries. In the list you will see that each country has an unique id. You can use this id to only retrieve the information of the specified country id. For instance:

GET - /countries/1/

This request will return all information about the country with id 1, in this case The Netherlands. The returned response can contain more information about the country then is available in the list of the countries.

Cities

The countries result contains information about each country and also contains URL's to retrieve cities within the specified country.

GET /countries/{country_id}/cities/

The response is a list of all the available cities within the specified country with a BimBimBikes partner company.

By specifying a city id the informatie of only the specified location is returned. The returned response can contain more information about the city then is available in the list of the cities.

GET /countries/{country_id}/cities/

For instance /countries/15/cities/15/ will return all available information about city with id 156 within the country with id 5.

Locations

The countries and cities result contain URL's to retrieve the locations within the specified city and country.

GET /countries/{country_id}/locations/ - Lists all locations within the specified country

GET /countries/{country_id}/cities/{city_id/locations/ - Lists all locations within the specified country and city

The response is a list of all the available locations within the specified country or city.

It is also possible to retrieve a list of all locations without using a country or cityid by requesting the locations endpoint.

GET /locations/

Each location has it's own id and url to retrieve information about this location. This url contains more information then the information of the location in the list. For instance:

GET /locations/3/

This request will return all information about the location with location id 3. The response will also contain url's to other resources that are connected to the location like the opening hours of a location or the available bikes.

The page_url field contains an URL to the rental company page. Appended to the URL is your partnerid. When visitor follows this link and makes a reservation the commission will be linked to your partner account. The URL has the following format:

https://www.bimbimbikes.com/bike-rental/netherlands/rotterdam/omi?partnerid=123

You can also append a maximum of 10 custom variables that will be saved with the reservation. These variables will be shown in your partner area for bookings that have been completed. You can use the following syntax:

https://www.bimbimbikes.com/.../omi?partnerid=123&vars[var1]=test1&vars[var2]=test2

Location bikes

It is possible to retrieve a list of all bikes that are available at the specified location. The type of bike, the prices and additional info is returned by requesting this endpoint:

GET /locations/{location_id}/bikes/

So for instance you can request /locations/2/bikes/ to retrieve the information of the bikes at location id 3.

By specifying a city id the informatie of only the specified location is returned. The returned response can contain more information about the city then is available in the list of the cities.

Location openinghours

It is possible to retrieve a list of openinghours of the specified location. For each weekday it will specify the openinghours by requesting this endpoint:

GET /locations/{location_id}/opening-hours/

So for instance you can request /locations/10/opening-hours/ to retrieve the openinghours of the location with id 10.

Reservation

It is possible to make a reservation by sending a POST request to the endpoint:

POST /reservation/

The request must contain the reservation info in JSON format in the body of the request.

{
    "location_id": 170,
    "reservation_length": 1,
    "reservation_date": "2016-01-19",
    "payment_method": "cardgate_ideal",
    "customer": {
        "email": "youremail@domain.com",
        "firstname": "John",
        "lastname": "Doe",
        "address_1": "Handelsplein 122",
        "address_2": "",
        "city": "Rottedam",
        "zipcode": "3071 PR",
        "country": "NL",
        "phone": "010-3007846"
    },
    "bikes": [
           {
               "id": 2,
               "quantity": 2
           }
    ]
}

Currently the following fields are supported in the request:

  • location_id : This is the id of the rental company location
  • reservation_length : The number of days that the bikes want to be rented. Minimum 1 day.
  • reservation_date : This is the start date of the reservation. This date must always be in the future.
  • payment_method : This is the payment method to use. A list of available payment methods can be retrieved at the /payment-methods/ endpoint.
  • customer.email : The emailaddress of the customer.
  • customer.firstname : The firstname of the customer.
  • customer.lastname : The lastname of the customer.
  • customer.address_1 : The address of the customer.
  • customer.address_2 : Optional: A second line for the address of the customer.
  • customer.city : The city of the customers address.
  • customer.zipcode : The zipcode of the customers address.
  • customer.country : The countrycode of the customers address.
  • customer.phone : The phonenumber of the customer.
  • bikes.id : The id of the bike to rent.
  • bikes.quantity : The number of bikes to rent of the specified bike id.

All fields are required except from the fields that are marked optional.

When the request contains an error a JSON response with the error is returned.

{
    "uuid": "3fc586ac-ffff-428b-b8af-e7f5d5b0b841",
    "date": "2016-01-18T10:33:11.493Z",
    "responsetime": "449ms",
    "message": {
        "error": "Reservation date cannot be in the past",
        "errorid": 4004,
        "statuscode": 400
    }
}

The message field contains a description of the error.

In case the request was successfull a JSON response is returned like the next example

{
    "uuid": "0d8ebb3c-e428-4f85-9423-534b468ac01c",
    "date": "2016-01-15T17:37:11.079Z",
    "responsetime": "885ms",
    "data": {
        "result": {
            "succes": true,
            "url": "http://bimbimtest-nl.oswshop.nl/app_dev.php/payment/capture/ik_dM0bLjc2RFja1ShahiG23lUgw1yTBIQSqPnphe20",
            "number": 203,
            "total": 1300
        }
    }
}

The response contains the following fields:

  • url : This is url to redirect the customer to make the payment.
  • number : This is the unique ordernumber of the reservation.
  • total: This is the total price of the reservation.

When you redirect the customer to the specified url he can make the payment with the requested payment method. If you want the customer to be redirected back to your website after the payment you can sent an email to info@bimbimbikes.com with you API key and the return url.