247Parking API

The REST API provides programmatic access to read and write 247Parking data. All requests needs to be authorized and responses are available in JSON.

Documentation

Below are the documents that will help you get going with the REST API as quickly as possible:

• Get access to the API
• Authenticate requests
• Make a reservation on the 247Parking platform

Feedback

If you find any issues with the API, please let us know via api@247parking.nl. We look forward to working with you and can’t wait to see your creations.

Error codes & responses

The 247Parking API attempts to respond with appropriate HTTP status codes for every request.

The meta key is used to communicate extra information about the response. If all goes well, you'll only see a code key with value 200, sometimes with an accompanying message. If things go wrong you might see a response like:

{
    "data": "",
    "meta": {
        "status": "error",
        "code": 401,
        "message": "Request expired"
    }
}

Request credentials

When you would like to get access to the 247Parking API, you can send your request to info@247parking.nl. After approval, you will get a partner account and your API credentials (API key and API secret).

Find API credentials

You can find your API Key and API Secret in your partner account. Login to your partner account on 247parking.nl/account and go to the API page. Here you can find your current API Key and API Secret. On this page you can also reset your credentials.

Authorizing a request

The purpose of this section is to show you how to modify HTTP requests for the purpose of sending authorized requests to the 247Parking API. The implementation requires that requests contain an additional HTTP X-Authorization header. An example of a HTTP request looks like this:

GET /v1/ HTTP/1.1
Host: api.247parking.nl
Connection: close
X-Authorization:
	Key="XxYEajBjyj&PQZiLGatPbKkoU3cg6NG9)ZrW6DWghAEiqv=lM",
	Timestamp="1420070400",
	Nonce="566761a9662108025d974494a55232d14cbbe945da87d6ab",
	Signature="G5OSm46rLM61WQlltBpe4qB57gk="

X-Authorization header parameters

The X-Authorization header contains 4 key/value pairs. For any given API request, collecting these 4 values and creating a similar header will allow you to specify authorization for the request. How each value was generated is described below.

API Key

The API Key identifies which partner account is making the request. Obtain this value from checking the settings page for your partner account on 247parking.nl/account.

Key XxYEajBjyj&PQZiLGatPbKkoU3cg6NG9)ZrW6DWghAEiqv=lM

Timestamp

The Timestamp parameter indicates when the request was created. This value should be the number of seconds since the Unix epoch at the point the request is generated. The API will reject requests which were created too long ago (older than 10 minutes).

Timestamp 1420070400

Nonce

The Nonce parameter is a unique token your application should generate for each unique request. The API will use this value to determine whether a request has been submitted multiple times. The value for this request was generated by base64 encoding 32 bytes of random data, and stripping out all non-word characters, but any approach which produces a relatively random alphanumeric string should be OK here.

Nonce 566761a9662108025d974494a55232d14cbbe945da87d6ab

Signature

The Signature parameter contains a value which is generated by running all of the other request parameters and the API Secret through a signing algorithm. The purpose of the signature is so that 247Parking can verify that the request has not been modified in transit and verify the partner sending the request.

The process for calculating the Signature for this request is described in Creating a signature.

Signature G5OSm46rLM61WQlltBpe4qB57gk=

Building the X-Authorization header string

To build the X-Authorization header string, imagine writing to a string named DST.

1. Append the string

   Key="

   parameter to DST
2. Append the API Key to DST
3. Append the string

   ",Timestamp="

   to DST
4. Append the Timestamp parameter to DST
5. Append the string

   ",Nonce="

   to DST
6. Append the Nonce parameter to DST
7. Append the string

   ",Signature="

   to DST
8. Append the Signature parameter to DST
9. Append a double quote

   "

   to DST

Performing these steps results in the following string:

Key="Key",Timestamp="Timestamp",Nonce="Nonce",Signature="Signature"

Key="XxYEajBjyj&PQZiLGatPbKkoU3cg6NG9)ZrW6DWghAEiqv=lM",Timestamp="1420070400",Nonce="566761a9662108025d974494a55232d14cbbe945da87d6ab",Signature="G5OSm46rLM61WQlltBpe4qB57gk="

This value should be set as the X-Authorization header for the request.

Creating a signature

This section explains how to generate a signature for a HTTP request. The signature will be suitable for passing to the 247Parking API as part of an authorized request, as described in Authorizing a request.

The request used to demonstrate signing is a GET request to https://api.247parking.nl/v1/. The raw request looks like this:

GET /v1/ HTTP/1.1
Host: api.247parking.nl
Connection: close
X-Authorization:
	Key="XxYEajBjyj&PQZiLGatPbKkoU3cg6NG9)ZrW6DWghAEiqv=lM",
	Timestamp="1420070400",
	Nonce="566761a9662108025d974494a55232d14cbbe945da87d6ab",
	Signature="G5OSm46rLM61WQlltBpe4qB57gk="

Parameters for the signature

To produce a signature, you need the following parameters: API Secret, HTTP method, base URL, nonce and timestamp.

API Secret

The API Secret identifies your application to 247Parking and can be found by going to 247parking.nl/account and viewing the settings page for your partner account. It is very important to note that these values are incredibly sensitive and should never be shared with anyone. This parameter will be the same for every request your application sends.

Secret YyZLGQZiGrW6oBjyj&WghAP9)ZEiqv=lMatPbK

HTTP method

The HTTP method is known when creating the request, so it is easy to obtain. The 247Parking API only accepts GET or POST requests. HTTP methods must be converted to uppercase.

HTTP method GET

Base URL

The Base URL is the URL to which the request is directed, minus any query string or hash parameters. Make sure that the URL starts with "https://".

Base URL https://api.247parking.nl/

Nonce

The Nonce parameter is generated when you authorize a request. The nonce is send as parameter in the X-Authorization header and is also used to generate the signature.

Nonce 566761a9662108025d974494a55232d14cbbe945da87d6ab

Timestamp

The last parameter is the Timestamp. This parameter is generated when you authorize a request. The timestamp is send as parameter in the X-Authorization header and is also used to generate the signature.

Timestamp 1420070400

Calculating the signature

Finally, the Signature is calculated by concatenating the parameters above and the SHA1 hashing algorithm (using the binary output). There are implementations of SHA1 available for every popular language. For example, PHP has the SHA1 function.

Concatenate the parameters in the following order:

concatenated_string = Secret HTTP method Base URL Nonce Timestamp

For the request in this example, the concatenated_string will look like this:

YyZLGQZiGrW6oBjyj&WghAP9)ZEiqv=lMatPbKGEThttps://api.247parking.nl/566761a9662108025d974494a55232d14cbbe945da87d6ab1420070400

This concatenated string is hashed with the SHA1 function, the output must be a binary string. This binary string needs to be base64 encoded to produce the signature string. That value is the signature for this request:

Signature G5OSm46rLM61WQlltBpe4qB57gk=

Reset API credentials

Should your API Key or API Secret become compromised or need to be invalidated for any reason, you can do so in your partner account. Login to your partner account on 247parking.nl/account and go to the API page. Here you can find your current API Key and API Secret. By clicking the 'Reset API credentials' button, you can invalidate your current API Key and API Secret, and create a new one.

Note: after resetting your API Key and API Secret, the previous credentials will be invalidated immediately.

GET /

Make a blank or test request to the 247Parking platform. You can use this endpoint for example to test your authorization settings.

Resource URL

Resource Information

Parameters

None

Example request

GET /v1/ HTTP/1.1
Host: api.247parking.nl
Connection: close
X-Authorization: Key="XxYEajBjyj&PQZiLGatPbKkoU3cg6NG9)ZrW6DWghAEiqv=lM",Timestamp="1420070400",Nonce="566761a9662108025d974494a55232d14cbbe945da87d6ab",Signature="G5OSm46rLM61WQlltBpe4qB57gk="

Example response

{
    "data": "",
    "meta": {
        "status": "success",
        "code": 200,
        "message": "Access authorized"
    }
}

POST /reservering/

Make a new reservation in the 247Parking platform.

Resource URL

Resource Information

Parameters

Example request

POST /v1/reservering/ HTTP/1.1
Host: api.247parking.nl
Connection: close
Content-Type: application/json
Content-Length: 431
X-Authorization: Key="XxYEajBjyj&PQZiLGatPbKkoU3cg6NG9)ZrW6DWghAEiqv=lM",Timestamp="1420070400",Nonce="566761a9662108025d974494a55232d14cbbe945da87d6ab",Signature="G5OSm46rLM61WQlltBpe4qB57gk="

{"klant_land":"Nederland","parkeerlocatie":"schiphol","vertrek_timestamp":"20-01-2015 13:30","vertrek_vluchtnummer":"HV 123","aankomst_timestamp":"29-01-2015 21:30","aankomst_vluchtnummer":"HV 456","parkeerservice":"shuttle","auto_merk_type":"Audi A3 zwart","auto_kenteken":"97-KGT-1","klant_voornaam":"John","klant_achternaam":"de Smit","klant_email":"john.de.smit@gmail.com","klant_mobiel":"0612345678","aantal_personen":"3","betalingswijze":"contant","kortingscode":"NYE2015"}

Example response

{
    "data": {
        "voucher_url": "https://247parking.nl/voucher.php?id=z0126c3a55fa10ba20fa12345",
        "reserveringsnummer": "S123456",
        "totaalprijs": "38.99"
    },
    "meta": {
        "status": "success",
        "code": 200,
        "message": "Reservering toegevoegd"
    }
}

Response with invalid value for kortingscode

{
  "data": "",
  "meta": {
    "status": "error",
    "code": 400,
    "message": "De ingevoerde kortingscode bestaat niet of is verlopen."
  }
}

PUT /reservering/:resnr/

Update an existing reservation in the 247Parking platform.

Resource URL

Resource Information

Parameters

Example request

PUT /v1/reservering/s123456/ HTTP/1.1
Host: api.247parking.nl
Connection: close
Content-Type: application/json
Content-Length: 233
X-Authorization: Key="XxYEajBjyj&PQZiLGatPbKkoU3cg6NG9)ZrW6DWghAEiqv=lM",Timestamp="1420070400",Nonce="566761a9662108025d974494a55232d14cbbe945da87d6ab",Signature="G5OSm46rLM61WQlltBpe4qB57gk="

{"vertrek_timestamp":"20-02-2017 05:30","aankomst_timestamp":"01-03-2017 23:30","parkeerservice":"shuttle","parkeerlocatie":"schiphol","betalingswijze":"ideal","klant_achternaam":"Test Persoon","totaalprijs":"39.99"}

Example response

{
    "data": {
        "voucher_url": "https://247parking.nl/voucher.php?id=123abc123abc123abc123abc",
        "reserveringsnummer": "S123456",
        "totaalprijs": "39.99"
    },
    "meta": {
        "status": "success",
        "code": 200,
        "message": "Booking updated"
    }
}

PUT /reservering/:resnr/status/

Update the status of an existing reservation in the 247Parking platform.

Resource URL

Resource Information

Parameters

Example request

PUT /v1/reservering/s123456/status/ HTTP/1.1
Host: api.247parking.nl
Connection: close
Content-Type: application/json
Content-Length: 19
X-Authorization: Key="XxYEajBjyj&PQZiLGatPbKkoU3cg6NG9)ZrW6DWghAEiqv=lM",Timestamp="1420070400",Nonce="566761a9662108025d974494a55232d14cbbe945da87d6ab",Signature="G5OSm46rLM61WQlltBpe4qB57gk="

{"status":"noshow"}

Example response

{
  "data": {
    "reserveringsnummer": "S123456"
  },
  "meta": {
    "status": "success",
    "code": 200,
    "message": "Booking status is updated to noshow"
  }
}