1. Geo-coding Addresses

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

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 basics about the API.

We'll provide some code examples using CURL and Python. You find a full description of our API in our API reference.

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

api_url = "https://<your_company_name>prd.smartlane.io/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:

{'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. You reference an address with its id. You can try requesting this address again via it's id by calling the /address endpoint with, like this:

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

api_url = "https://<your_company_name>prd.smartlane.io/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 the address, represented by its geo-coordinates.

If you don't provide the geo-coordinates, we do the geo-coding. Send a POST request to the /address endpoint with a valid address and look at the result.

curl --request POST \
     --url 'https://<your_company_name>prd.smartlane.io/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://<your_company_name>prd.smartlane.io/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
}

We added the geo-location represented in the GeoJSON encoding, with the geocoordinates given as an array in the format ["lattitute", "longitute"].

Validating Adresses - Bad Data

Not every request to the /address endpoint responds with a valid geo-coded address. In this case you get a

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

message and the shipment will be dropped from the planning.
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.