Using Location History Segments via the API
Follow

Our geo-location feature set is available as part of our Comprehensive paid service account. In addition, you must implement location reporting in your app. See the Related Content section at the bottom of this article for more information.

This article includes information pertaining only to our Location History product. This article does not include information about geofencing or iBeacons. For more on the difference see Can you do Geofencing with Segments?

There are a number of steps you will need to complete to gather the information you need, create the segment, and send a push notification to the segment.

Step 1: Get location IDs

Use an API request similar to this to look up locations for a given search term (note Portland in query string):

curl -X GET -u "<appkey>:<mastersecret>" -H "Content-Type: application/json" https://go.urbanairship.com/api/location/?q=Portland

This request returns locations related to Portland. The response should look something like this:

{"features":[
{"type":"Feature","id":"77dJ9IiWz64TWYujUUGYf3","properties":{"source":"naturalearthdata.com","boundary_type_string":"Urban Area","boundary_type":"urbanarea","name":"Portland"},"bounds":[45.275,-123.008333,45.75,-122.308333],"centroid":[45.513259,-122.65541]},{"type":"Feature","id":"1H4pYjuEW0xuBurl3aaFZS","properties":{"source":"tiger.census.gov","boundary_type_string":"City/Place","name":"Portland","context":{"us_state_name":"Oregon","us_state":"OR"},"boundary_type":"city"},"bounds":[45.432393,-122.83675,45.653272,-122.472021],"centroid":[45.537179,-122.650037]},{"type":"Feature","id":"6Rq1ED3N3jFaw4zPWK7Sgd","properties":{"source":"tiger.census.gov","boundary_type_string":"City/Place","name":"Portland","context":{"us_state_name":"Maine","us_state":"ME"},"boundary_type":"city"},"bounds":[43.544348,-70.347399,43.727686,-69.975851],"centroid":[43.647081,-70.168234]},
... (more entries)

You will want to parse out the id field from this response. For instance, 77dJ9IiWz64TWYujUUGYf3.

These IDs can also be found on your Urban Airship dashboard under Audience > Segments > New Segment.

Step 2: Create the Segment

Create the segment with an API request:

{
  "display_name": "name_of_segment",
  "criteria": {
    "and": [
      {
        "location": {
          "id": "location_id_from_above",
          "date": {
            "recent": {
              "months": 3
            }
          }
        }
      }
    ]
  }
}

You can create segments with AND / OR logic to include multiple locations.

Creating very complex segments in this way can lead to significant delays in push delivery and is not recommended.

The response from this request will include the segment_id, which you'll need to push to that segment.

Step 3: Example push API JSON payloads

iOS:

{
  "audience": {
    "segment": "segment_id_here"
  },
  "device_types": [
    "ios"
  ],
  "notification": {
    "alert": "Segment test iOS, v3"
  }
}

Android:

{
  "audience": {
    "segment": "segment_id_here"
  },
  "device_types": [
    "android"
  ],
  "notification": {
    "alert": "Segment test Android, v3"
  }
}

iOS and Android:

{
  "audience": {
    "segment": "segment_id_here"
  },
  "device_types": [
    "ios",
    "android"
  ],
  "notification": {
    "alert": "Segment test both, v3"
  }
}

iOS and Android to multiple segments with AND (device must exist in both segments to receive notification):

{
  "audience": {
    "AND": [
      {
        "segment": "first_segment_id_here"
      },
      {
        "segment": "second_segment_id_here"
      }
    ]
  },
  "device_types": [
    "ios",
    "android"
  ],
  "notification": {
    "alert": "v3 two-segment and test"
  }
}

iOS and Android to multiple segments with OR (device can exist in either segment to receive notification):

{
  "audience": {
    "or": [
      {
        "segment": "first_segment_id_here"
      },
      {
        "segment": "second_segment_id_here"
      }
    ]
  },
  "device_types": [
    "ios",
    "android"
  ],
  "notification": {
    "alert": "v3 two-segment or test"
  }
}

Using Location History Segments via the API Follow

Step 1: Get location IDs

Step 2: Create the Segment

Step 3: Example push API JSON payloads

Related Content:

Using Location History Segments via the API
Follow