Mobility Services

Get Periodic Country Events

Periodic country events are events that for each subscriber's SIM card will look at it's current country location and the time since last event sent for that same SIM card for that country. Each operator will have a time interval configured for this event, and the event will happen whenever a subscriber is seen in a country for which this event has not been sent for that time.

NOTE that this API responds with the IMSI for the SIM card in the user's handset. This is considered PII information and needs to be handled with care.

This event is triggered:

  • When the subscriber first turns on the device and it connects to a network, it will be triggered for the country of the connected network at the same time as the corresponding 'FirstAttachment' event.
  • When the subscriber enters a new country (not visited before). This is triggered at the same time as the corresponding 'CountryChange' event.
  • When the subscriber is seen in a country, and the 'PeriodicCountry' event for that subscriber and country has not been triggered for the configured time delay.

Prerequisites

  1. An OAuth 2.0 client
  2. A client access token

Required Scope

  • subscription.periodic_country:read

Code Dependencies

kotlin
Copy<dependency>
  <groupId>com.wgtwo.api.v1.grpc</groupId>
  <artifactId>subscription</artifactId>
  <version>1.10.1</version>
</dependency>

Code

If targeting production, you would need to add authentication to the sample code.

gRPCurl
kotlin
Copy
#!/usr/bin/env bash
grpcurl \
  -d '
  {
    "stream_configuration": {
      "regular": {},
      "disable_explicit_ack": {}
    }
  }
  ' \
  sandbox.api.shamrock.wgtwo.com:443 \
  wgtwo.subscription.v1.SubscriptionEventService/StreamPeriodicCountryEvents

Copy
package com.example.periodiccountry

import com.wgtwo.api.v1.subscription.SubscriptionEventServiceGrpc
import com.wgtwo.api.v1.subscription.SubscriptionEventsProto.AckPeriodicCountryEventRequest
import com.wgtwo.api.v1.subscription.SubscriptionEventsProto.StreamPeriodicCountryEventsRequest
import com.wgtwo.api.v1.subscription.SubscriptionEventsProto.StreamPeriodicCountryEventsResponse
import io.grpc.ManagedChannelBuilder
import io.grpc.StatusRuntimeException
import java.util.concurrent.Executors

private const val MAX_IN_FLIGHT = 10

private val channel = ManagedChannelBuilder.forAddress("sandbox.api.shamrock.wgtwo.com", 443).build()
private val stub = SubscriptionEventServiceGrpc.newBlockingStub(channel)
private val executor = Executors.newFixedThreadPool(MAX_IN_FLIGHT)

fun main() {
    while (!channel.isShutdown) {
        try {
            subscribe()
        } catch (e: StatusRuntimeException) {
            println("Got exception: ${e.status} - Reconnecting in 1 second")
            Thread.sleep(1000)
        }
    }
}

private fun subscribe() {
    println("Starting subscription")
    val request = StreamPeriodicCountryEventsRequest.newBuilder().apply {
        streamConfigurationBuilder.maxInFlight = MAX_IN_FLIGHT
    }.build()

    stub.streamPeriodicCountryEvents(request).forEach { response ->
        // Using an executor to handle up to MAX_IN_FLIGHT messages in parallel
        executor.submit {
            handleResponse(response)
            ack(response)
        }
    }
}

private fun handleResponse(response: StreamPeriodicCountryEventsResponse) {
    println("Got response:
$response")
}

private fun ack(response: StreamPeriodicCountryEventsResponse) {
    val ackInfo = response.metadata.ackInfo
    val request = AckPeriodicCountryEventRequest.newBuilder().setAckInfo(ackInfo).build()
    stub.ackPeriodicCountryEvent(request)
}

Example Result

gRPCurl
kotlin
Copy{
  "periodicCountryEvent": {
    "number": {
      "e164": "+47xxxxxxxx"
    },
    "imsi": {
      "value": "242xxyyyyyyyyyy"
    },
    "country": {
      "code": "NO",
      "name": "Norway"
    }
  }
}
{
  "periodicCountryEvent": {
    "number": {
      "e164": "+47xxxxxxxx"
    },
    "imsi": {
      "value": "242xxyyyyyyyyyy"
    },
    "country": {
      "code": "SE",
      "name": "Sweden"
    }
  }
}

Copyperiodic_country_event {
  number {
    e164: "+47xxxxxxxx"
  }
  imsi {
    value: "242xxyyyyyyyyyy"
  }
  country {
    code: "NO"
    name: "Norway"
  }
}

# Ack success

periodic_country_event {
  number {
    e164: "+47xxxxxxxx"
  }
  imsi {
    value: "242xxyyyyyyyyyy"
  }
  country {
    code: "SE"
    name: "Sweden"
  }
}

# Ack success

Read More

Next