Since December of 2004, Google has provided an annual Christmas-themed site which allows users to track Santa during Christmas Eve. Additionally, NORAD has been tracking Santa since 1955. While no official API exists, there is an unofficial API which can be used to track Santa’s whereabouts.
In celebration of the Christmas season, I wanted to create a Spring Boot application that could be used to get updates on Santa’s location via SMS. The full code for this Java application can be found on GitHub.
First, I want to explain how the application works on a higher level. Then we can dive into some of the more challenging problems, and ways to work around them.
See it in Action
When an SMS is received on my Nexmo number, a payload gets sent to my registered webhook. Information such as the sender's phone number and the message contents are then used to determine how to respond to the message.
Here's how it looks in action:
The Initial Message
The first time a message is received, the user is always presented with Santa's current location. They are also asked if they would like to provide their postal code to get distance information.
Location Lookup
Location lookup is not a trivial task. Postal codes are not consistent worldwide, and it helps to know which country the user is contacting from in order to narrow down our search.
If the user elects to provide postal code information, I use Nexmo Number Insight to lookup the country that they are sending messages from. They are then asked to provide their postal code. From this, I use a service called GeoNames to lookup the latitude and longitude for that postal code.
This information gets saved in the database along with their phone number. The latitude and longitude is used to calculate how far Santa is from them:
Getting More Technical
At its surface, the application doesn't seem all that complicated. However, there are quite a few challenges that I ran into during the development process. I'd like to highlight some of the more technical aspects of the code.
Routing Incoming Messages
My Nexmo number is configured to send POST
requests to a webhook URL. I have an IncomingMessageController
setup to handle the incoming messages:
@PostMapping
public void post(@RequestParam("msisdn") String from,
@RequestParam("to") String nexmoNumber,
@RequestParam("keyword") String keyword,
@RequestParam("text") String text
) {
Phone phone = findOrCreatePhone(from, nexmoNumber);
findHandler(phone, keyword).handle(phone, text);
}
The findOrCreatePhone
method is used to persist a new Phone
entity, or to lookup an existing entity. Here's what the phone entity looks like:
@Entity
public class Phone {
@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
private Long id;
private String number;
private String nexmoNumber;
private String countryCode;
@Enumerated(EnumType.STRING)
private Stage stage;
@OneToOne
private Location location;
// Getters and Setters
}
The entity contains the phone number, the Nexmo number, a country code, and the current stage that the user is in. I will talk about the Stage
enum in a later section.
The findHandler
method is used to lookup an appropriate KeywordHandler
to handle the message:
public interface KeywordHandler {
void handle(Phone phone, String text);
}
Each handler is responsible for handling a specific keyword. The keywords that the application knows about are:
- HELP which provides contextual information to assist the user.
- CANCEL which cancels the current series of questions.
- REMOVE which removes the user from the database.
- YES in which the user is responding to the question in the affirmative.
- NO in which the user is responding to the question in the negative.
- WHERE which responds with Santa's current location.
- LOCATION which allows the user to update their location.
Each KeywordHandler
is registered as a Spring Managed Bean. The HelpKeywordHandler
, for example, looks like this:
@Component
public class HelpKeywordHandler implements KeywordHandler {
@Override
public void handle(Phone phone, String text) {
// Logic here
}
}
All of the KeywordHandler
implementations are injected into a keywordHandler
map on the IncomingMessageController
:
private final Map<String, KeywordHandler> keywordHandlers;
@Autowired
public IncomingMessageController(Map<String, KeywordHandler> keywordHandlers) {
this.keywordHandlers = keywordHandlers;
}
When injecting into a map, Spring will use camelCase
class names as the key, and the instantiated class as the value. For example, the HelpKeywordHandler
is stored with the key helpKeywordHandler
:
HelpKeywordHandler handler = keywordHandlers.get("helpKeywordHandler");
The appropriate KeywordHandler
is then picked using a variant of the Strategy Pattern. If no valid KeywordHandler
is found, then the DefaultKeywordHandler
is used to respond.
private KeywordHandler findHandler(Phone phone, String keyword) {
// New users should always go to the default handler
if (phone.getStage() == null) {
return keywordHandlers.get("defaultKeywordHandler");
}
KeywordHandler handler = keywordHandlers.get(keywordToHandlerName(keyword));
return (handler != null) ? handler : keywordHandlers.get("defaultKeywordHandler");
}
private String keywordToHandlerName(String keyword) {
return keyword.toLowerCase() + "KeywordHandler";
}
Routing messages like this allows for flexibility when new keywords need to be added.
Handling the Various Stages
Each handler is responsible for messages that start with its keyword. However, how does the YesKeywordHandler
know which question the user is responding to? This is where the Stage
enum inside of the Phone
class comes in.
The Phone
entity can exist in the following intermediary stages:
-
No Stage (
null
) for users that have just been created and have not been asked a question yet. -
INITIAL
for users who have been responded to with the first message containing Santa's location and a prompt on whether or not they would like to provide a postal code. -
COUNTRY_PROMPT
for users who have been asked if their country code is correct. -
POSTAL_PROMPT
for users who have been asked to provide a postal code.
Once the questions have been asked, they are put in the following final stages:
-
REGISTERED
for users who have provided a postal code and will receive more detailed information. -
GUEST
for users who did not wish to provide postal code information and will only receive Santa's current location with no distance calculated.
This is how the YesKeywordHandler
uses stages:
@Override
public void handle(Phone phone, String text) {
if (phone.getStage() == Phone.Stage.INITIAL) {
handlePromptForCountryCode(phone);
} else if (phone.getStage() == Phone.Stage.COUNTRY_PROMPT) {
handlePromptForPostalCode(phone);
} else {
outgoingMessageService.sendUnknown(phone);
}
}
A user that is answering in the INITIAL
stage must be answering the question "Would you like to provide postal code information?"
A user answering in the COUNTRY_PROMPT
stage must be answering the question "I see you're messaging from the US. Reply YES, a 2-character country code, or CANCEL if you've changed your mind."
Getting the Country Code
In order to lookup the postal code more accurately, it helps to know the country the user is messaging from. I created a PhoneLocationLookupService
which uses Nexmo Basic Number Insight to lookup the country information for the phone number:
@Service
public class PhoneLocationLookupService {
private final InsightClient insightClient;
@Autowired
public PhoneLocationLookupService(NexmoClient nexmoClient) {
this.insightClient = nexmoClient.getInsightClient();
}
public String lookupCountryCode(String number) {
try {
return this.insightClient.getBasicNumberInsight(number).getCountryCode();
} catch (IOException | NexmoClientException e) {
return null;
}
}
}
The application will ask the user to confirm their country just in case they are travelling and want to set themselves in a different country instead.
Lookup for Postal Codes
It turns out that looking up latitude and longitude information for postal codes is not a trivial task. I chose to work with GeoNames because the service is free.
I created a PostCodeLookupService
to handle looking up the postal code information. The getLocation
method first looks to see if we already know about the postal code in the database. This is a good practice as it helps limit the number of calls to the third party service.
If there isn't an existing Location
entity, the third party service is called, and a new entity is persisted. If we couldn't find a location matching that postal code, we return an empty Optional
so that the application knows to ask the user to try again:
private Optional<Location> getLocation(String country, String postalCode) {
Optional<Location> locationOptional = locationRepository.findByPostalCode(postalCode);
if (locationOptional.isPresent()) {
return locationOptional;
}
LocationResponse response = getLocationResponse(country, postalCode);
if (response.getPostalCodes().isEmpty()) {
return Optional.empty();
}
Location newLocation = buildLocation(response, postalCode);
return Optional.of(locationRepository.save(newLocation));
}
Calculating Distance
Once we have the user's latitude and longitude we can lookup Santa's current location and use a formula to determine how far away the user is from Santa. This is done in the DistanceCalculationService
:
public double getDistanceInMiles(double lat1, double lng1, double lat2, double lng2) {
double theta = lng1 - lng2;
double dist = Math.sin(Math.toRadians(lat1))
* Math.sin(Math.toRadians(lat2))
+ Math.cos(Math.toRadians(lat1))
* Math.cos(Math.toRadians(lat2))
* Math.cos(Math.toRadians(theta));
dist = Math.acos(dist);
dist = Math.toDegrees(dist);
dist = dist * 60 * 1.1515;
return dist;
}
Conclusion
This was a look into how one might create an application that allows you to get Santa's location updates via SMS. We covered routing messages based on keywords, using multiple stages to determine which questions a user is responding to, and using Nexmo Number Insight to get the country code for a phone number.
For more detailed information, I would recommend looking at the code on GitHub. The README
file contains all the information you need to get up and running with the application itself.
Be sure to check out Google's Santa Tracker or NORAD Santa Tracker around Christmas Eve as an additional way to keep tabs on Santa.
Top comments (0)