7 days of WordPress plugins, themes & templates - for free!* Unlimited asset downloads! Start 7-Day Free Trial
  1. Code
  2. APIs

Using Social Media to Locate Eyewitnesses to Important Events

Scroll to top
Read Time: 10 mins
This post is part of a series called Using Social Media to Locate Eyewitnesses.
Using Social Media to Locate Eyewitnesses: The Twitter API
Final product imageFinal product imageFinal product image
What You'll Be Creating

This is the first of a two-part series on using social media to locate eyewitnesses to important events. In this tutorial, I'll guide you through using the Instagram API to find members that might have been near a 2013 Macklemore video shoot and a Seattle accident scene near where I often work. 

In part two, we'll use the Twitter API to find members near another recent event. I'll also address some of the privacy issues related to social media and sharing your geolocation. You can download code for each episode by using the GitHub repository link in the sidebar. You may also be interested in my Tuts+ series, Building With the Twitter API.

I do participate in the discussions. If you have a question or topic suggestion, please post a comment below. You can also reach me on Twitter @reifman or email me directly. 

Using Geotagging for Good (and Evil)

The phones we carry in our pockets record our every move, sharing it with cell providers and often third party software companies whose motivations generally focus on profit. But it's not just phones and GPS that expose us—I almost always make purchases with credit cards, exposing pretty much every aspect of my life to credit card providers, hackers, or legal requests.

Wired's Vanish Contest

In Wired's 2009 Vanish contest, I helped lead the capture of journalist Evan Ratliff. After writing about people who fake their deaths, Ratliff tried to disappear for 30 days as part of an experiment. If anyone could find him in person before time expired, they'd receive a $5,000 prize. Using a Facebook application as a honeypot, I was able to lure Ratliff into repeatedly sharing his location via IP address, which I then verified against a Twitter account I'd discovered he was using. With help from other Vanish participants nationwide, we called in help on the ground in New Orleans—which came in the form of a gluten-free pizza shop (Ratliff was known to be celiac) who managed to track him down in town. In that story, geotagging wasn't used to find him but IP address geolocation. You can read Ratliff's story here as well.

But social media applications on our phone frequently make use of geotagging, leaving a trail that users don't always anticipate.

Muckraking With Geotags and Social Media

Many people don't realize that they've left geotagging on their social media apps, fully publicizing their location with every social media post. This included GOP Congressman Aaron Schock. The AP used his Instagram account's geotags to expose his use of taxpayer funds for extravagant private flights and other luxurious activities. See Instagram account exposes congressman who blew public funds on private flights and concerts.

Here's an Instagram post by Schock from Patagonia—notice the geotag icon beside "Perito Moreno Glacier":

Congressman Aaron Shock at the Perito Moreno GlacierCongressman Aaron Shock at the Perito Moreno GlacierCongressman Aaron Shock at the Perito Moreno Glacier

So, investigating geotags can be used for good. In this tutorial, I'm going to explore how journalists or law enforcement might locate potential eyewitnesses to important events such as a crime or accident scene using social media.

However, geotagging can also be used for evil. There are definitely important privacy implications of its integration into our digital lifestyle.

Privacy Implications

Berkeley computer scientists and educators built the Ready or Not? app to showcase how geotagging in Twitter and Instagram record our every move. See also Is Your Twitter Account Saying Too Much? 

Here's Congresmmen Schock's Instagram account in the Ready or Not? app:

Congressman Aaron Shock Worldwide Travels - Ready or NotCongressman Aaron Shock Worldwide Travels - Ready or NotCongressman Aaron Shock Worldwide Travels - Ready or Not

Here's Apple co-founder Steve Wozniak's Twitter account in the app. Interesting that the congressman's travel is even more widespread than this tech tycoon.

Steve Wozniaks Travels on Twitter - Ready or NotSteve Wozniaks Travels on Twitter - Ready or NotSteve Wozniaks Travels on Twitter - Ready or Not

The geotagging on Instagram and Twitter is accurate enough to allow someone to easily determine your residence, place of work and travel routine.

Turning Off Geotagging

If you don't wish to share your location for the public to see, or to leave a historical trail of your travels, the Ready or Not? app offers links and guides to turning these features off (look for the link on its home page). Frankly, I've turned mine off and I encourage you to do so too.

For those that don't—and many won't—their social media posts may be useful to law enforcement looking for witnesses to a crime scene or journalists wishing to dig deeper into a story. I'm going to guide you through how to do that. 

In this episode, I'll guide you through using the Instagram API. I've provided a GitHub repository (the link is in the sidebar) for you to download to try out the code. My "Eyewitness app" is written in the Yii Framework for PHP, which you can learn more about in my Programming With Yii2 series for Tuts+

The configuration process requires that you register a developer account and application with Instagram (and/or Twitter). 

If you're a law enforcement agency or media entity that would like more information, please feel free to contact me directly. I would also be interested in any successful uses of this code (for good)—they'd make an interesting follow-up story.

Using the Instagram API

Let's begin with Instagram. If you don't yet have an Instagram account, download the application on your phone and sign up.

Instagram Media Search 

The geolocation search on Instagram is quite sophisticated and offers a very straightforward interface for our purposes. As you can see below, we need to provide a location's latitude and longitude, a geographic radius (distance) and a time range (min_timestamp and max_timestamp):

Instagram Media SearchInstagram Media SearchInstagram Media Search

Getting Started

Visit the Instagram API page for developers and click Register Your Application:

Instagram Hello DevelopersInstagram Hello DevelopersInstagram Hello Developers

You'll need to sign up for a developer account:

Instagram Developer SignupInstagram Developer SignupInstagram Developer Signup

Then you can register a new application to receive your Client ID:

Instagram New Client RegistrationInstagram New Client RegistrationInstagram New Client Registration

On the Manage Clients dashboard, you'll see your Client ID and Client Secret, so make note of these:

Instagram Manage ClientsInstagram Manage ClientsInstagram Manage Clients

Installing the Eyewitness Codebase

You can clone the GitHub repository located in the sidebar to run our sample code.

You'll need to configure your local Apache configuration. I use MAMP, so it looks something like this:

You need to create a database locally. I use PHPMyAdmin to create one graphically:

Create your Eyewitness databaseCreate your Eyewitness databaseCreate your Eyewitness database

Then I create an initialization file in /var/secure/eyew.ini with my database credentials and Instagram IDs and keys. I described this process recently in another Tuts+ tutorial: Protecting Your Keys From GitHub. Humorously, I accidentally checked in my Instagram key during testing (sigh) and had to reset my keys afterwards.

My ini file looks like this:

Update your Composer and its vendor libraries:

Then initialize our database. The first migration installs user tables for our Yii2-User by developer Dmeroff extension, and the second creates our app-specific tables:

Again, you can learn more about setting up a Yii Framework application in my Programming With Yii2 series for Tuts+.

The Eyewitness Home Page

Here's a look at what you should see when you visit the site in your browser:

Eyewitness Home PageEyewitness Home PageEyewitness Home Page

Define a Moment

A Moment is a place and time for which we're looking for social media posters who were present. It consists of a friendly descriptor, a location (latitude and longitude), a start time and a duration (in minutes). For my first example, I'm looking for Instagram users who were present at Macklemore's video shooting on the evening of Wednesday, July 24, 2013 at Seattle's landmark Dick's Drive In. The video production and ensuing crowds shut down the area for hours.

Using Google Maps, I can get the GPS latitude and longitude for Dick's. It's 47.6195 -122.321. 

Dicks Drive In Broadway Seattle GPS in Google MapsDicks Drive In Broadway Seattle GPS in Google MapsDicks Drive In Broadway Seattle GPS in Google Maps

From the article, I learned that the production shut down at 1 am. I'm going to choose a start time of 10 pm and a duration of 3 hours.

Create a MomentCreate a MomentCreate a Moment

Instagram accepts start times in GMT so I've hardcoded an eight hour time change adjustment from my timezone (PST). You may need to change this in the code.

Moment Search on Instagram

To search Instagram, we click the camera icon below:

The Moments Index GridThe Moments Index GridThe Moments Index Grid

To implement my media search on Instagram, I'm using Galen Grover's Instagram PHP package. The actual search is fairly straightforward: $instagram->searchMedia( $this->latitude, $this->longitude,$params ); 

The results are stored in my Gram table, which we can then browse:

Browse the Results

Here's the first page of results from my search. You can see the crowds and Macklemore's Cadillac limo driving up. Clearly, I hit the jackpot with my search.

Macklemore Search ResultsMacklemore Search ResultsMacklemore Search Results

Then on page three, an Instagram user named Joshua Lewis has a shot of Macklemore exiting the Cadillac: 

More Macklemore Search ResultsMore Macklemore Search ResultsMore Macklemore Search Results

Here's Macklemore:

Macklemore Arrives on InstagramMacklemore Arrives on InstagramMacklemore Arrives on Instagram

This example clearly shows the power that the Instagram search API provides. In just a few moments, we found a variety of eyewitnesses to an event from the summer of 2013. Amazing.

If you're interested, here's a YouTube video of that Macklemore shoot:

Another Example Moment

For my second example, I'm going to search for Instagram users who were in the area around the time of a tragic accident near where I was co-working a few weeks ago. A woman's motorized scooter may have malfunctioned and she lost control, crashing into the tail end of a passing car (thankfully, she survived). It happened in front of the Starbuck's "Roastery", an unfortunate new tourist trap here in Seattle (I'm not a fan). 

Using Google Maps, we can see the GPS coordinates of the roastery to be 47.614264, -122.328008:

Starbucks Roastery in Seattle GPS in Google MapsStarbucks Roastery in Seattle GPS in Google MapsStarbucks Roastery in Seattle GPS in Google Maps

The article tells us that the accident happened around 5 pm. So we'll use this information to create our Moment:

Create a Second momentCreate a Second momentCreate a Second moment

Here you can see both moments we've added:

List of Your MomentsList of Your MomentsList of Your Moments

In case you were wondering, the eraser icon purges past results for that moment search.

Here's the results for our Starbucks Roastery accident search. No one posted photos of the accident scene—common courtesy prevailed. However, all of these Instagram users were in the area at the time and might be worth contacting as witnesses. 

Instagram Media Search for Starbucks Roastery AccidentInstagram Media Search for Starbucks Roastery AccidentInstagram Media Search for Starbucks Roastery Accident

Some were tourists like this Russian woman—I've posted the Google translation of her Instagram post below:

Instagram Media Search for Starbucks Roastery Accident Russian TouristInstagram Media Search for Starbucks Roastery Accident Russian TouristInstagram Media Search for Starbucks Roastery Accident Russian Tourist

Others visited the Starbucks roastery tasting room or a nearby bar and oyster restaurant.

I hope that you can see both the dark and the light of geotagging technology. There are obvious legitimate uses that these technologies can provide for good, and they can obviously be abused.

What's Next?

In the next episode, we're going to implement searching moments using the Twitter API.

In the meantime, please feel free to post your questions and comments below. You can also reach me on Twitter @reifman or email me directly. I'd especially appreciate hearing from journalists and law enforcement that make use of these examples.

You can also browse my Tuts+ instructor page to see other tutorials I've written. 

Related Links

Did you find this post useful?
Want a weekly email summary?
Subscribe below and we’ll send you a weekly email summary of all new Code tutorials. Never miss out on learning about the next big thing.
Looking for something to help kick start your next project?
Envato Market has a range of items for sale to help get you started.