Shipment API

API change history

REST JSON interface that exposes methods related to:

  • Submitting a shipment to the notime platfom
  • Checking a shipment's status
  • Cancelling a shipment
  • Updating shipment parameters after submission

4. Get Services

This method is used in order to enquire real-time about the notime services available for a certain ZIP code.
A service could be a home delivery of goods from a central warehouse or shop in the city (defined by configuration) or delivery of a product to a Pickup Point where end-users can pick up goods by themselves.

For example we might have a 7-9 pm delivery time window to Zürich which represents one service. Another service might be the home delivery on Saturday between 5 and 7 pm.
The services that are availabe depend on your contractual agreement with notime. For more information please contact us on info@notime.eu.

Each service is identified through a unique identifier (GUID). This GUID can be used in the method Submit Shipment as an alternative method to providing data.

Try it

Request URL

Request parameters

string

Guid identifying your shipper account. For testing purposes you can use the ID: 28228CFE-12F2-4BFB-B8BF-B7FF87746E96. Your account manager will provide you with your unique ID before going into production.

string

Postcode of the location where the goods shall be delivered to

(optional)
number

Desired language of the response if applicable. Possibe values are 1: German 2: English 3: French. Default is 1.

(optional)
number

Defines duration of the period starting from the date/time specified in the field from in days, for which available services shall be returned. Applicable range is 1..14. Default value is 3.

(optional)
number

Defines what types of services shall be returned. Contact us on info@notime.eu for details.

(optional)
string

Defines the UTC starting time of the period for which available services shall be returned. Default value is current time. Format is: yyyy-MM-ddTHH:mm:ssZ. E.g. "2015-10-29T12:10:00Z"

Request headers

string
Subscription key which provides access to this API. Found in your Profile.

Request body

Response 200

Returned in case the submitted parameters fit the validation rules.

The following object is returned:

Name Type Description
ResultCode Int
  • 0: No Error
  • 99: Validation Error
Data Array of Service Available services
ErrorString String Error description
Success Boolean True if request processed successfully


Name Type Description
Id String Unique identifier (GUID) of the service. This can be used in the Submit Shipment method
TimeFrom UTC date time string (yyyy-MM-ddTHH:mm:ssZ) Service is available from this time
TimeTo UTC date time string (yyyy-MM-ddTHH:mm:ssZ) Service is available until this time
Currency String
Fee Double Fee that the consumer will have to pay for the service
PaymentType Int Payment type available to the consumer. Possible values are:
  • 1: Cash
  • 2: Credit card
If it is not set any payment type could be used
Type Int One of the ServiceType values
Explanation String Long description of the service. This description can be used as explanatory text on the website or confirmation email. It also offers easier integration of 3rd-party systems.
FriendlyName String Brief description of the service. This description can be used in a dropdown menu to let the consumer choose the service. It also offers easier integration of 3rd-party systems.

Type Description
1 Home Delivery
2 Home Pickup
4 Pickup Point 

{  
   "ResultCode":0,
   "Data":[  
      {  
         "Id":"F0AD15F6-EB64-4E0C-9495-0EE7C47E397F",
         "FriendlyName":"CHF 15.00 - Home Delivery: 09.05 14:00-16:00",
         "Explanation":"Your order will be delivered to your home on 09.05 between 14:00 and 16:00. Prior you will receive a \"FollowMe\" SMS or email from us. With FollowMe you can change the delivery time window or the delivery options later on.",
         "TimeFrom":"2017-05-09T13:00:00Z",
         "TimeTo":"2017-05-09T15:00:00Z",
         "Type":1,
         "Fee":15.0,
         "Currency":"CHF",
         "PaymentType":1
      }
   ],
   "ErrorString":null,
   "Success":true
}

Response 400

Returned in case the submitted parameters do not fit the validation rules.

{  
   "ResultCode":99,
   "Data":null,
   "ErrorString":"{\"GroupGuid\":[\"The GroupGuid field is required.\"]}",
   "Success":false
}

Code samples

@ECHO OFF

curl -v -X GET "https://v1.notimeapi.com/api/service?groupGuid={string}&postCode={string}&language=1&countDays=3&services={number}&from={string}"
-H "Ocp-Apim-Subscription-Key: {subscription key}"

--data-ascii "{body}" 

using System;
using System.Net.Http.Headers;
using System.Text;
using System.Net.Http;
using System.Web;

namespace CSHttpClientSample
{
    static class Program
    {
        static void Main()
        {
            MakeRequest();
            Console.WriteLine("Hit ENTER to exit...");
            Console.ReadLine();
        }
        
        static async void MakeRequest()
        {
            var client = new HttpClient();
            var queryString = HttpUtility.ParseQueryString(string.Empty);

            // Request headers
            client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", "{subscription key}");

            // Request parameters
            queryString["groupGuid"] = "{string}";
            queryString["postCode"] = "{string}";
            queryString["language"] = "1";
            queryString["countDays"] = "3";
            queryString["services"] = "{number}";
            queryString["from"] = "{string}";
            var uri = "https://v1.notimeapi.com/api/service?" + queryString;

            var response = await client.GetAsync(uri);
        }
    }
}	
// // This sample uses the Apache HTTP client from HTTP Components (http://hc.apache.org/httpcomponents-client-ga/)
import java.net.URI;
import org.apache.http.HttpEntity;
import org.apache.http.HttpResponse;
import org.apache.http.client.HttpClient;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.client.utils.URIBuilder;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.util.EntityUtils;

public class JavaSample 
{
    public static void main(String[] args) 
    {
        HttpClient httpclient = HttpClients.createDefault();

        try
        {
            URIBuilder builder = new URIBuilder("https://v1.notimeapi.com/api/service");

            builder.setParameter("groupGuid", "{string}");
            builder.setParameter("postCode", "{string}");
            builder.setParameter("language", "1");
            builder.setParameter("countDays", "3");
            builder.setParameter("services", "{number}");
            builder.setParameter("from", "{string}");

            URI uri = builder.build();
            HttpGet request = new HttpGet(uri);
            request.setHeader("Ocp-Apim-Subscription-Key", "{subscription key}");


            // Request body
            StringEntity reqEntity = new StringEntity("{body}");
            request.setEntity(reqEntity);

            HttpResponse response = httpclient.execute(request);
            HttpEntity entity = response.getEntity();

            if (entity != null) 
            {
                System.out.println(EntityUtils.toString(entity));
            }
        }
        catch (Exception e)
        {
            System.out.println(e.getMessage());
        }
    }
}


<!DOCTYPE html>
<html>
<head>
    <title>JSSample</title>
    <script src="http://ajax.googleapis.com/ajax/libs/jquery/1.9.0/jquery.min.js"></script>
</head>
<body>

<script type="text/javascript">
    $(function() {
        var params = {
            // Request parameters
            "groupGuid": "{string}",
            "postCode": "{string}",
            "language": "1",
            "countDays": "3",
            "services": "{number}",
            "from": "{string}",
        };
      
        $.ajax({
            url: "https://v1.notimeapi.com/api/service?" + $.param(params),
            beforeSend: function(xhrObj){
                // Request headers
                xhrObj.setRequestHeader("Ocp-Apim-Subscription-Key","{subscription key}");
            },
            type: "GET",
            // Request body
            data: "{body}",
        })
        .done(function(data) {
            alert("success");
        })
        .fail(function() {
            alert("error");
        });
    });
</script>
</body>
</html>

#import <Foundation/Foundation.h>

int main(int argc, const char * argv[])
{
    NSAutoreleasePool * pool = [[NSAutoreleasePool alloc] init];
    
    NSString* path = @"https://v1.notimeapi.com/api/service";
    NSArray* array = @[
                         // Request parameters
                         @"entities=true",
                         @"groupGuid={string}",
                         @"postCode={string}",
                         @"language=1",
                         @"countDays=3",
                         @"services={number}",
                         @"from={string}",
                      ];
    
    NSString* string = [array componentsJoinedByString:@"&"];
    path = [path stringByAppendingFormat:@"?%@", string];

    NSLog(@"%@", path);

    NSMutableURLRequest* _request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:path]];
    [_request setHTTPMethod:@"GET"];
    // Request headers
    [_request setValue:@"{subscription key}" forHTTPHeaderField:@"Ocp-Apim-Subscription-Key"];
    // Request body
    [_request setHTTPBody:[@"{body}" dataUsingEncoding:NSUTF8StringEncoding]];
    
    NSURLResponse *response = nil;
    NSError *error = nil;
    NSData* _connectionData = [NSURLConnection sendSynchronousRequest:_request returningResponse:&response error:&error];

    if (nil != error)
    {
        NSLog(@"Error: %@", error);
    }
    else
    {
        NSError* error = nil;
        NSMutableDictionary* json = nil;
        NSString* dataString = [[NSString alloc] initWithData:_connectionData encoding:NSUTF8StringEncoding];
        NSLog(@"%@", dataString);
        
        if (nil != _connectionData)
        {
            json = [NSJSONSerialization JSONObjectWithData:_connectionData options:NSJSONReadingMutableContainers error:&error];
        }
        
        if (error || !json)
        {
            NSLog(@"Could not parse loaded json with error:%@", error);
        }
        
        NSLog(@"%@", json);
        _connectionData = nil;
    }
    
    [pool drain];

    return 0;
}

<?php
// This sample uses the Apache HTTP client from HTTP Components (http://hc.apache.org/httpcomponents-client-ga/)
require_once 'HTTP/Request2.php';

$request = new Http_Request2('https://v1.notimeapi.com/api/service');
$url = $request->getUrl();

$headers = array(
    // Request headers
    'Ocp-Apim-Subscription-Key' => '{subscription key}',
);

$request->setHeader($headers);

$parameters = array(
    // Request parameters
    'groupGuid' => '{string}',
    'postCode' => '{string}',
    'language' => '1',
    'countDays' => '3',
    'services' => '{number}',
    'from' => '{string}',
);

$url->setQueryVariables($parameters);

$request->setMethod(HTTP_Request2::METHOD_GET);

// Request body
$request->setBody("{body}");

try
{
    $response = $request->send();
    echo $response->getBody();
}
catch (HttpException $ex)
{
    echo $ex;
}

?>
########### Python 2.7 #############
import httplib, urllib, base64

headers = {
    # Request headers
    'Ocp-Apim-Subscription-Key': '{subscription key}',
}

params = urllib.urlencode({
    # Request parameters
    'groupGuid': '{string}',
    'postCode': '{string}',
    'language': '1',
    'countDays': '3',
    'services': '{number}',
    'from': '{string}',
})

try:
    conn = httplib.HTTPSConnection('v1.notimeapi.com')
    conn.request("GET", "/api/service?%s" % params, "{body}", headers)
    response = conn.getresponse()
    data = response.read()
    print(data)
    conn.close()
except Exception as e:
    print("[Errno {0}] {1}".format(e.errno, e.strerror))

####################################

########### Python 3.2 #############
import http.client, urllib.request, urllib.parse, urllib.error, base64

headers = {
    # Request headers
    'Ocp-Apim-Subscription-Key': '{subscription key}',
}

params = urllib.parse.urlencode({
    # Request parameters
    'groupGuid': '{string}',
    'postCode': '{string}',
    'language': '1',
    'countDays': '3',
    'services': '{number}',
    'from': '{string}',
})

try:
    conn = http.client.HTTPSConnection('v1.notimeapi.com')
    conn.request("GET", "/api/service?%s" % params, "{body}", headers)
    response = conn.getresponse()
    data = response.read()
    print(data)
    conn.close()
except Exception as e:
    print("[Errno {0}] {1}".format(e.errno, e.strerror))

####################################
require 'net/http'

uri = URI('https://v1.notimeapi.com/api/service')

query = URI.encode_www_form({
    # Request parameters
    'groupGuid' => '{string}',
    'postCode' => '{string}',
    'language' => '1',
    'countDays' => '3',
    'services' => '{number}',
    'from' => '{string}'
})

if uri.query && uri.query.length > 0
    uri.query += '&' + query
else
    uri.query = query
end

request = Net::HTTP::Get.new(uri.request_uri)
# Request headers
request['Ocp-Apim-Subscription-Key'] = '{subscription key}'
# Request body
request.body = "{body}"

response = Net::HTTP.start(uri.host, uri.port, :use_ssl => uri.scheme == 'https') do |http|
    http.request(request)
end

puts response.body