Geo location - Ortto help

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 Ortto, 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.

Requests to geolocate a person within an activity event are submitted as a single POST method to the following URL:


 https://api.ap3api.com/v1/activities/create

NOTE: Ortto customers who have their instance region set to Australia or Europe will need to use specific service endpoints relative to the region:

Australia: https://api.au.ap3api.com/
Europe: https://api.eu.ap3api.com/

For example: https://api.eu.ap3api.com/v1/<entity/endpoint>

All other Ortto users will use the default service endpoint (https://api.ap3api.com/).

Geolocate by IP address

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

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

shell
 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"
            }
          }
        ]
      }'

Ortto 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. For example, if a person (contact) has both source_ip and country_name values, the proximity filters would defer to IP first.

Geolocate by known location information (custom)

The next method is referred to as custom in the Ortto 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:

shell
 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
             }
           }
         }
       ]}'

NOTE:

Combining IP and custom

You can provide both the source_ip 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 postal address using the address key to locate them exactly.

NOTE:

Geolocating by address (address lookup) costs extra

All the geolocation features of the Ortto API are included in your plan, with the exception of location lookup using the address key. That is, if you are looking up a location using source_ip or custom (you provide all the location information), there is no additional charge.

Geolocation by address 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.

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

shell
 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:

shell
 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.