Smartlane API

The Smartlane API Developer Hub

Welcome to the Smartlane API developer hub. You'll find comprehensive guides and documentation to help you start working with the Smartlane API as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

1. Geocoding Addresses

Addresses define destinations for Deliveries. They come as a bundle of the actual human readable address information and the geolocation.

Feel free skip this chapter, if you provide your own geocoordinates otherwise learn here how our address recogition system works, or if a short overview is enough for you, take a look at our basic data structures page.

Some Basics about Addresses and the API in general

An address that is usually already in our system is the one you provided by signing up, your company address. A GET request to the /companyaddress enpoint, provides another good test to check if you're signed up properly as was explained in the previous chapter and gives an oppertunity to learn some basic stuff about the API.

We'll provide some code examples using CURL and Python and there are auto generated example requests in a couple of other langagues in our API reference. Don't take them too seriously, but we hope you don't have any troubles translating them to your language of choice. So let's get started.

curl --request GET \
     "https://dispatch.smartlane.io/your_company_name/api/companyaddress" \
     --header "Authorization: JWT your.Long_Randomfghxlcnebem.Secure_AccessToken"
import requests

api_url = "https://dispatch.smartlane.io/your_company_name/api/companyaddress"

auth_header = {'Authorization': 'JWT your.Long_Randomfghxlcnebem.Secure_AccessToken'}

response = requests.get(url, headers=auth_header)

You should get a response from our server that shows our address schema. It looks something like this:

{'num_results': 1,
 'objects': [{'id': 1,
              'customernr': None,
              'contactcompany': 'Company Name',
              'contactfirstname': 'Test',
              'contactlastname': 'User',
              'email': None,
              'phonenr': None,
              'street': 'Grafinger Straße',
              'housenumber': '6',
              'postalcode': '81671',
              'city': 'München',
              'country': 'Germany',
              'location': {'coordinates': [11.60772, 48.12469],
                           'type': 'Point'},
              'addresstype': 'depot',
              'default_pdt_from': None,
              'default_pdt_to': None,
              'deliverylocations': [],
              'distances': None,
              'district': None,
              'additional': None,
              'code': None,
              'source_for_deliveries': []}]}

You can find all the typical properties of an address in this JSON response, like contactlastname, street, housenumber and city.
Ignore most of the properties for now, but let's discuss an important one briefly - the id. And you already know it, you have seen it as the location_id of your company from the previous chapter, which was precisly a reference to this particular entry in the address table of our database.

This already gives some insights into the structure of our system and yes, of course, there's database running in the background and it's using the good old relational model (at least on the surface exposed by our API). Basically all data comes with these ids. You own your data and this way you can always address it directly. But usually you don't have to care about all this stuff, and we're putting quite some effort in to make your life as a developer as convenient as possible.

You can try requesting this address again via it's id by calling the /address endpoint with, like this:

curl --request GET \
     "https://dispatch.smartlane.io/your_company_name/api/address/1" \
     --header "Authorization: JWT your.Long_Randomfghxlcnebem.Secure_AccessToken"
import requests

api_url = "https://dispatch.smartlane.io/your_company_name/api/address/1"

auth_header = {'Authorization': 'JWT your.Long_Randomfghxlcnebem.Secure_AccessToken'}

response = requests.get(url, headers=auth_header)

Or simply get all addresses by calling the /address endpoint without an id

curl --request GET \
     "https://dispatch.smartlane.io/your_company_name/api/address" \
     --header "Authorization: JWT your.Long_Randomfghxlcnebem.Secure_AccessToken"
import requests

api_url = "https://dispatch.smartlane.io/your_company_name/api/address"

auth_header = {'Authorization': 'JWT your.Long_Randomfghxlcnebem.Secure_AccessToken'}

response = requests.get(url, headers=auth_header)

📘

Pagination

Some of the responses are "paginated" by default. To request a specific page, add a page=N query parameter to the request URL, where N is a positive integer, e.g. /api/company?page=2.

Geocoding Addresses

So the main information necessary to carry out a delivery is ..., yes, the address, but not quite, it's actually the geocoordinates, our algroithms work with.

But no worries, you post an address, we do the geocoding. Just try it, by sending a POST request to the /address endpoint.

curl --request POST \
     --url 'https://dispatch.smartlane.io/your_company_name/api/address' \
     --header 'Content-Type: application/json' \
     --header 'Authorization: JWT your.Long_Randomfghxlcnebem.Secure_AccessToken' \
     --data '{"contactcompany": "The Supply Center",
              "street": "Grafinger Str.",
              "housenumber": "6",
              "city": "München",
              "postalcode": "81671"}'
import requests

auth_header = {"Authorization": "JWT your.Long_Randomfghxlcnebem.Secure_AccessToken"}
api_url = "https://dispatch.smartlane.io/your_company_name/api"

url = api_url + "address"

data = {"contactcompany": "The Supply Center",
        "street": "Grafinger Str.",
        "housenumber": "7",
        "city": "München",
        "postalcode": "81671"}

response = requests.post(url, headers=auth_header, json=data)

If everything went right, you've added an entry to the address database and should get a response similar to the following

{'id': 2,
 'contactcompany': 'The Next Door Company',
 'contactfirstname': null,
 'contactlastname': null,
 'street': 'Grafinger Str.',
 'housenumber': '7',
 'postalcode': '81671',
 'city': 'München',
 'country': 'DE',
 'district': null,
 'location': {'coordinates': [11.6080874, 48.1251596], 'type': 'Point'},
 'customernr': null,
 'email': null,
 'phonenr': null,
 'addresstype': null,
 'default_pdt_from': null,
 'default_pdt_to': null,
 'code': null,
 'distances': null
}

And voilà, there is the geolocation represented in the GeoJSON encoding, with the geocoordinates given as an array in the format ["lattitute", "longitute"].
But unfortunately it's not always that simple ...

Validating Andresses - Bad Data

Not every request to the /address endpoint responds with a valid geocoded address. Just think about the (non existing) address example:

{'street': 'Keinestr.',
           'housenumber': 49
           'city': "Notown",
           'postalcode': "91238",
           'country': "Germany"
}

A post to /address response with the following message

{'message': 'no location could be found for this address'}

implying that no address has been saved to our database, as the mandatory geolocation property could not be provided.

So how do we decide, weather an address is valid? We get our Address data from Here, therefore an address is decided to be valid if it can be recognized by Here's Geocoder API.

But the devil is in the details, and expectations vary a lot with customers.
On the one side, you only want addresses in the system that are correct, so you can send your drivers to these locations with confidence. On the other side, you don't want the system to break on every typo in a city's name.

We provide a couple of settings, that help you bridge this gap in the process of validating addresses. Please contact us for more details concerning your use case.

Updated about a year ago

1. Geocoding Addresses


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.