Geo location

Having location information about your customers can help you create targeted marketing campaigns. Being able to say "show me all the clients within 10 km of my store who have not purchased in the last month" can be extremely valuable.

Within Autopilot, we have several ways to get location information via our API. The general principle being, provide us with all the artifacts of data you have, and we will pinpoint the nearest location.

Geolocate by IP address

The simplest way to locate your customers is to provide their IP address any time you send an activity into Autopilot.

Below is an example of using cURL to send a request containing an IP address:

curl --location\
     --request POST 'https://api.ap3api.com/v1/activities/create'\
     --header 'X-Api-Key: PUT-YOUR-REAL-KEY-HERE'\
     --header 'Content-Type: application/json'\
     --data-raw '{
	"activities": [
          {
            "activity_id":"act:cm:logged-in",
            "fields": {
              "str::email": "chris.smith@example.com"
            },
            "attributes": {
              "bol:cm:example":true
            },
            "location": {
              "source_ip": "59.167.135.194"
            }
          }
        ]
      }'

Autopilot will lookup an approximate location based on this IP address and use it as the "last seen" location for this customer. It can also be used in proximity based filters. The IP address is effective enough for most proximity queries, and usually very easy to do in most web applications.

Geolocate by known location information

The next method is referred to as "custom" in the Autopilot API and asks you to provide any known location information about the customer that you can. Latitude (lat) and Longitude (lng) are the most accurate, but the idea is to provide known values and let the system determine the most specific location it can.

Below is an example of using cURL to send a request containing location details:

curl --location\
     --request POST 'https://api.ap3api.com/v1/activities/create'\
     --header 'X-Api-Key: PUT-YOUR-REAL-KEY-HERE'\
     --header 'Content-Type: application/json'\
     --data-raw '{
       "activities": [
         {
           "activity_id":"act:cm:logged-in",
           "fields": {
             "str::email": "chris.smith@example.com"
           },
           "attributes": {
             "bol:cm:example":true
           },
           "location": {
             "custom": {
               "country_name": "Australia",
               "region_name": "Sydney",
               "city_name": "Gladesville",
               "position_name": "Central Perk Cafe",
               "lat": -33.83333,
               "lng": 151.13333
             }
           }
         }
       ]}'

Combining IP and custom

You can provide both the source_id and custom keys in your API call and our system will use whichever provides the most specific location, usually custom.

Geolocate by address

If you want to get very specific with location, which is important for many e-commerce stores, you can specify the customer’s address to locate them exactly.

Below is an example of using cURL to send a request containing address details:

curl --location\
     --request POST 'https://api.ap3api.com/v1/activities/create'\
     --header 'X-Api-Key: PUT-YOUR-REAL-KEY-HERE'\
     --header 'Content-Type: application/json'\
     --data-raw '{
       "activities": [
         {
           "activity_id":"act:cm:logged-in",
           "fields": {
             "str::email": "chris.smith@example.com"
           },
           "attributes": {
             "bol:cm:example":true
           },
           "location": {
             "address": {
               "address": "71 Princes Street, Ryde, NSW 2112",
               "boost_region": "au"
             }
           }
         }
       ]}'

For this method, there are some additional advanced options to increase the likelihood of a successful address match. The below cURL example contains these additional options:

curl --location\
     --request POST 'https://api.ap3api.com/v1/activities/create'\
     --header 'X-Api-Key: PUT-YOUR-REAL-KEY-HERE'\
     --header 'Content-Type: application/json'\
     --data-raw '{
       "activities": [
         {
           "activity_id":"act:cm:logged-in",
           "fields": {
             "str::email": "chris.smith@example.com"
           },
           "attributes": {
             "bol:cm:example":true
           },
           "location": {
             "address": {
               "address": "75 Princes St",
               "postal_code": "2112",
               "country": "Australia",
               "boost_region": "au"
              }
            }
          }
        ]}'

Boost fields

The boost_region and language fields will increase the likelihood of a local match for the address. So if you know them, provide them. They only help the engine locate the address.

Filter fields

The postal_code and country fields are filters which means if the engine matches an address not in that postcode or not in that country, it will be ignored.

Address lookup costs extra

All the geolocation features of the Autopilot API are included in your plan, with the exception of looking up via postal address. This feature is pay-as-you go, costing $10 per 1000 lookups, rounded up each month to the nearest 1000. Address lookup is only available on Business plans or higher. If you are on a lower than business plan, the address lookup will fail, and you will receive an error.