Creating an IRS-Compliant Mileage Log by Parsing Google Timeline JSON Data with Python

/ Blog (EN), Tax / By

Creating an IRS-Compliant Mileage Log by Parsing Google Timeline JSON Data with Python

The Internal Revenue Service (IRS) in the United States allows taxpayers to deduct expenses related to the business use of their vehicles, but this requires meticulous and accurate mileage logs. Manual record-keeping is tedious and prone to errors. Leveraging digital tools like Google Timeline offers a more efficient approach. This article provides a comprehensive, expert tax advisor’s perspective on how to parse Google Timeline’s exported JSON data using Python to automatically generate an IRS-compliant mileage log.

Introduction

The IRS permits self-employed individuals and freelancers to claim unreimbursed car expenses (such as gas, maintenance, insurance, and depreciation) as business deductions under specific conditions. To substantiate these claims, detailed records, including a mileage log that meets IRS requirements, are mandatory. Key information typically required includes:

  • Date of the trip
  • Total miles driven (odometer reading)
  • Miles driven for business purposes
  • Percentage of business miles driven
  • Starting point and destination
  • Name of the person or business visited

Manually tracking this information is time-consuming, labor-intensive, and increases the risk of omissions or inaccuracies. The complexity escalates when multiple vehicles are involved or frequent travel is necessary. Google Timeline, a feature of Google accounts that records location history via smartphones, can automate the collection of travel data, which can then be processed. This article will guide you through the practical steps of using Python to efficiently process this Google Timeline data and transform it into an IRS-ready mileage log.

Basics

To fully grasp this process, understanding a few fundamental concepts is essential.

IRS Mileage Log Requirements

The IRS mandates detailed records to verify the business use of a vehicle. The primary requirements are:

  • Timeliness: Records should be kept contemporaneously, meaning at the time of each trip or as soon as reasonably possible thereafter.
  • Content: As mentioned in the introduction, logs must include date, total mileage, business mileage, destination, and business purpose.
  • Record-Keeping Method: Records can be in various formats, such as a written log, a spreadsheet, or a dedicated mileage tracking app, as long as they are accurate and complete.
  • Definition of Business Use: IRS defines business use as travel that is directly related to generating income. This includes visiting clients, purchasing supplies, attending business meetings, or traveling to a temporary work location. Commuting from home to your regular place of business is generally not considered deductible business mileage.

Failure to meet these requirements can result in the denial of mileage-based tax deductions. Therefore, maintaining accurate and comprehensive records is paramount.

What is Google Timeline?

Google Timeline is a service within your Google account that records and displays your location history. When location services are enabled on your Android or iOS device using the Google Maps app, it automatically logs your movements. This history is accessible via a web browser through your Google account, visualizing your routes and places visited on a map.

Beyond visualizing personal travel patterns, Google Timeline offers a feature to export this data in JSON format. The exported JSON file contains detailed information, including timestamps, latitude/longitude coordinates, and place names, serving as the raw data for our mileage log.

What is JSON Data?

JSON (JavaScript Object Notation) is a lightweight data-interchange format that is easy for humans to read and write and easy for machines to parse and generate. It is commonly used in web applications for transmitting data between a server and a client. JSON data is structured as key-value pairs and uses objects ({}) and arrays ([]) to represent data hierarchically.

A simplified example of the JSON structure exported from Google Timeline looks like this:


{
  "timelineItems": [
    {
      "time": "2023-10-27T09:00:00.000Z",
      "latitudeE7": 340522389,
      "longitudeE7": -1182437805,
      "accuracy": 15,
      "velocity": 5,
      "activity": [
        {
          "type": "STATIONARY",
          "confidence": 99
        }
      ]
    },
    {
      "time": "2023-10-27T09:30:00.000Z",
      "latitudeE7": 340530000,
      "longitudeE7": -118250000,
      "accuracy": 10,
      "velocity": 15,
      "activity": [
        {
          "type": "IN_VEHICLE",
          "confidence": 95
        }
      ]
    }
    // ... more timeline items
  ]
}

Understanding this structure is the first step towards parsing it with Python.

What is Python?

Python is a popular, versatile, and highly readable programming language widely used in data analysis, web development, automation, and more. Its rich ecosystem of libraries, such as NumPy and Pandas, makes it exceptionally well-suited for data manipulation and numerical computations, ideal for this task.

Detailed Analysis

Let’s break down the specific steps to parse Google Timeline JSON data with Python and create an IRS-compliant mileage log.

1. Preparing Google Timeline Data

First, you need to export your Google Timeline data.

  1. Log in to your Google Account.
  2. Go to Google My Activity: myactivity.google.com.
  3. Select ‘Timeline’ from the left-hand menu.
  4. Click the gear icon (Settings) in the top right corner of the Timeline screen.
  5. Find and click the link for ‘Download your data’ or ‘Google Takeout’.
  6. On the Google Takeout page, select the data you wish to export. Look for options related to ‘Location History’ or ‘Timeline’.
  7. Choose ‘.zip’ as the file format and click ‘Create export’.
  8. You will receive an email with a download link once the export is complete. Download the ZIP file and extract its contents. Inside, you will find JSON data files, possibly organized by date or as a single large file.

Note: Exporting can take time. Also, ensure your privacy settings have enabled location history recording for the period you wish to export.

2. Setting Up Your Python Environment

To perform data analysis with Python, you need the right tools.

  • Install Python: If you haven’t already, download and install the latest version from Python.org.
  • Install Necessary Libraries: For data analysis, the Pandas library is invaluable. Open your command prompt or terminal and run: 
    pip install pandas pytz timezonefinder geopy
    • Pandas: A powerful library for data manipulation and analysis, providing the DataFrame structure.
    • pytz: Handles time zone calculations in Python.
    • timezonefinder: Determines the time zone from latitude and longitude.
    • geopy: Performs geospatial calculations, like distance computation.

3. Loading and Preprocessing JSON Data

Load the exported JSON file into Python and preprocess it into a usable format.


import json
import pandas as pd
import pytz
from timezonefinder import TimezoneFinder
from geopy.distance import geodesic

# Specify the path to your JSON file
json_file_path = 'your_google_timeline_data.json' # Replace with your actual file path

# Load the JSON data
with open(json_file_path, 'r', encoding='utf-8') as f:
    data = json.load(f)

# Extract data from 'timelineItems'
timeline_items = data.get('timelineItems', [])

# Convert to Pandas DataFrame
df = pd.DataFrame(timeline_items)

# Select and rename necessary columns (optional)
df = df[['time', 'latitudeE7', 'longitudeE7', 'activity', 'velocity']]
df.rename(columns={'time': 'timestamp_str', 'latitudeE7': 'lat_e7', 'longitudeE7': 'lon_e7'}, inplace=True)

# Convert timestamp to datetime object
# Google Timeline timestamps are in UTC, so parse them as such initially
df['timestamp_utc'] = pd.to_datetime(df['timestamp_str'], utc=True)

# Convert latitudeE7 and longitudeE7 by dividing by 10^7
df['latitude'] = df['lat_e7'] / 1e7
df['longitude'] = df['lon_e7'] / 1e7

# Drop unnecessary columns
df.drop(columns=['lat_e7', 'lon_e7', 'timestamp_str'], inplace=True)

# Convert to local time, considering time zones (optional, but useful)
tf = TimezoneFinder()
def get_local_time(row):
    tz_str = tf.timezone_at(lng=row['longitude'], lat=row['latitude'])
    if tz_str:
        try:
            tz = pytz.timezone(tz_str)
            return row['timestamp_utc'].astimezone(tz)
        except pytz.UnknownTimeZoneError:
            return row['timestamp_utc'] # Return UTC if timezone is unknown
    return row['timestamp_utc'] # Return UTC if coordinates are invalid

df['timestamp_local'] = df.apply(get_local_time, axis=1)

# Keep timezone-aware UTC timestamp for consistency
df['timestamp_utc_aware'] = df['timestamp_utc'].dt.tz_convert('UTC')

# Sort DataFrame by timestamp
df.sort_values(by='timestamp_utc', inplace=True)

print("DataFrame after preprocessing (first 5 rows):")
print(df.head())

4. Identifying Travel Segments and Calculating Distance

Identify movements between consecutive timestamps and calculate the distance covered. The IRS requires total mileage, so identifying distinct travel segments is crucial.

This example calculates the straight-line distance between consecutive points and sums them up. Note that this is an approximation; for precise road distances, you’d need a service like the Google Maps Distance Matrix API. We’ll use the simpler geodesic distance here.


# Get the previous latitude and longitude
df['prev_latitude'] = df['latitude'].shift(1)
df['prev_longitude'] = df['longitude'].shift(1)

# Calculate distance between two points (using geopy's geodesic distance)
def calculate_distance(row):
    if pd.isna(row['prev_latitude']) or pd.isna(row['prev_longitude']):
        return 0.0
    current_loc = (row['latitude'], row['longitude'])
    prev_loc = (row['prev_latitude'], row['prev_longitude'])
    return geodesic(prev_loc, current_loc).miles # Calculate in miles

df['distance_miles'] = df.apply(calculate_distance, axis=1)

# Calculate cumulative distance
df['cumulative_distance_miles'] = df['distance_miles'].cumsum()

# Identify moving segments (e.g., if current location differs from previous)
# A more sophisticated approach could use 'activity' or 'velocity'
df['is_moving'] = (df['latitude'] != df['prev_latitude']) | (df['longitude'] != df['prev_longitude'])
df.loc[df['is_moving'].isna(), 'is_moving'] = False # First row is not considered moving

# Filter for moving segments if needed
# moving_df = df[df['is_moving']].copy()

print("DataFrame after calculating travel segments (first 5 rows):")
print(df.head())

5. Determining Business Purpose and Generating the Log

This is the most critical and challenging step. Google Timeline data alone cannot automatically determine if a trip was for business purposes. This information must be added manually or through a separate process.

Logic Examples for Determination:

  • Location-Based: Classify trips to specific locations (e.g., office, client sites, suppliers) as business.
  • Time-Based: Consider trips during typical business hours as potentially business-related (with exceptions).
  • Activity-Based: Use activity types like ‘IN_VEHICLE’ to infer movement.
  • Manual Entry: The most reliable method is to review the travel history and manually input the purpose and destination details.

For simplicity, this example marks potential business trips by excluding known personal locations (like home) and flagging other movements. In practice, you might manage this data in a spreadsheet and merge it with the Python script’s output.

Step 1: Identify Trip Start and End Points

Group consecutive movements into distinct trips. Identify the start and end points of each trip.


# Detect changes in movement status to identify trip starts and ends
df['movement_change'] = df['is_moving'].ne(df['is_moving'].shift()).fillna(False)

# Trip start: is_moving is True and there was a change, or it's the first row and moving
df['trip_start'] = (df['is_moving'] & df['movement_change']) | (df.index == df.index.min() & df['is_moving'])
# Trip end: is_moving is False and there was a change, or it's the last row and not moving
df['trip_end'] = (~df['is_moving'] & df['movement_change']) | (df.index == df.index.max() & ~df['is_moving'])

# Assign a trip ID
df['trip_id'] = df['trip_start'].cumsum()

# Aggregate data for each trip
trips = []
for trip_id, group in df.groupby('trip_id'):
    # Filter for groups that actually contain movement
    if group['is_moving'].any():
        # Find the first and last row *within the group* that marks the start/end of the trip
        start_idx = group[group['trip_start']].index.min()
        end_idx = group[group['trip_end']].index.min()
        
        # If start/end indices are not found correctly within the moving segment, adjust logic
        # For simplicity, we take the first and last point of the moving segment group
        if start_idx not in group.index: start_idx = group.index.min()
        if end_idx not in group.index: end_idx = group.index.max()

        actual_start_point = df.loc[start_idx]
        actual_end_point = df.loc[end_idx]
        
        # Calculate total distance for the trip using cumulative distances
        start_cumulative_dist = df.loc[start_idx, 'cumulative_distance_miles']
        end_cumulative_dist = df.loc[end_idx, 'cumulative_distance_miles']
        trip_distance = end_cumulative_dist - start_cumulative_dist
        
        # Calculate duration
        start_time = actual_start_point['timestamp_utc']
        end_time = actual_end_point['timestamp_utc']
        duration = end_time - start_time
        
        trips.append({
            'trip_id': trip_id,
            'start_time_utc': start_time,
            'end_time_utc': end_time,
            'duration': duration,
            'start_lat': actual_start_point['latitude'],
            'start_lon': actual_start_point['longitude'],
            'end_lat': actual_end_point['latitude'],
            'end_lon': actual_end_point['longitude'],
            'distance_miles': trip_distance,
            'start_address': None, # To be filled later
            'end_address': None,   # To be filled later
            'purpose': 'Unspecified', # To be filled manually
            'business_miles': None    # To be filled manually
        })

trips_df = pd.DataFrame(trips)

# Reverse geocode start/end points to get addresses (optional, can be slow)
# from geopy.geocoders import Nominatim
# from geopy.extra.rate_limiter import RateLimiter

# geo_locator = Nominatim(user_agent="google_timeline_parser")
# reverse_geocode = RateLimiter(geo_locator.reverse, min_delay_seconds=1)

# def get_address(lat, lon):
#     try:
#         location = reverse_geocode(f"{lat}, {lon}")
#         if location:
#             return location.address
#     except Exception as e:
#         print(f"Error geocoding {lat}, {lon}: {e}")
#     return None

# Use dummy addresses for demonstration
trips_df['start_address'] = [f'Start Address {i}' for i in range(len(trips_df))]
trips_df['end_address'] = [f'End Address {i}' for i in range(len(trips_df))]

# Add columns required by IRS format
trips_df['date'] = trips_df['start_time_utc'].dt.strftime('%Y-%m-%d')
trips_df['total_miles'] = trips_df['distance_miles']
trips_df['business_miles'] = None # Needs manual input
trips_df['purpose'] = 'Unspecified' # Needs manual input

# Define final log columns and order
final_log_columns = [
    'date',
    'start_address',
    'end_address',
    'total_miles',
    'business_miles',
    'purpose'
]

# Select and reorder columns for the final log
final_log = trips_df[final_log_columns].copy()

print("Generated trip log (before manual completion):")
print(final_log)

Step 2: Manual Completion

Save the generated `final_log` DataFrame as a CSV file. Open it in a spreadsheet program (like Excel or Google Sheets) and fill in the missing details for each trip:

  • `business_miles`: The number of miles driven for business purposes. This is a portion of the `total_miles`.
  • `purpose`: The specific reason for the trip. Examples: “Client A Visit”, “Supplier Meeting”, “Business Lunch”, “Site Inspection”.

Important Considerations:

  • Trips starting from home to the first business location or from the last business location back home may qualify as business miles, depending on your specific circumstances and IRS guidelines (e.g., if your home is also your principal place of business).
  • Commuting mileage (regular travel between your home and regular place of work) is generally not deductible.
  • For ambiguous locations, make a note or record them as personal if they don’t serve a business purpose.

6. Finalizing and Saving the IRS-Compliant Log

After manual completion, review the log in your spreadsheet software for accuracy and completeness. Save it in a suitable format (e.g., CSV). This finalized log can then be attached to your tax return.

Automating with Python (Advanced):

A more advanced approach could involve pre-defining key locations (home, office) and automatically classifying trips to/from these locations as ‘Personal’ or ‘Commute’. Other trips could be flagged as ‘Potential Business’. Integrating with calendar data could further enhance automated purpose prediction, though this significantly increases complexity.


# Example: Define home and office coordinates
HOME_LAT, HOME_LON = 34.0522, -118.2437 # Example: Los Angeles
OFFICE_LAT, OFFICE_LON = 34.0600, -118.2500 # Example: Office Location

# Function to classify trips based on proximity to home/office
def classify_trip(row):
    start_dist_home = geodesic((row['start_lat'], row['start_lon']), (HOME_LAT, HOME_LON)).miles
    end_dist_home = geodesic((row['end_lat'], row['end_lon']), (HOME_LAT, HOME_LON)).miles
    start_dist_office = geodesic((row['start_lat'], row['start_lon']), (OFFICE_LAT, OFFICE_LON)).miles
    end_dist_office = geodesic((row['end_lat'], row['end_lon']), (OFFICE_LAT, OFFICE_LON)).miles
    
    threshold = 0.5 # Miles, adjust as needed

    is_start_home = start_dist_home < threshold
    is_end_home = end_dist_home < threshold
    is_start_office = start_dist_office < threshold
    is_end_office = end_dist_office < threshold

    # Commute: Home to Office or Office to Home
    if (is_start_home and is_end_office) or (is_start_office and is_end_home):
        return 'Commute'
    # Personal: Entire trip within home/office zone
    elif (is_start_home and is_end_home) or (is_start_office and is_end_office):
        return 'Personal'
    # Trips starting/ending at home/office (potential business context)
    elif is_start_home or is_end_home or is_start_office or is_end_office:
        return 'Potential Business Context'
    else:
        # Trips not near home or office are likely business
        return 'Potential Business'

# Apply the classification (optional - requires careful tuning and understanding)
# trips_df['inferred_purpose'] = trips_df.apply(classify_trip, axis=1)

# You could use 'inferred_purpose' to pre-fill 'purpose' and 'business_miles'
# For example:
# trips_df['purpose'] = trips_df.apply(lambda row: row['inferred_purpose'] if row['inferred_purpose'] != 'Commute' and row['inferred_purpose'] != 'Personal' else 'Commute/Personal', axis=1)
# trips_df['business_miles'] = trips_df.apply(lambda row: row['distance_miles'] if row['inferred_purpose'] != 'Commute' and row['inferred_purpose'] != 'Personal' else 0, axis=1)

# IMPORTANT: Automated classification is a guide. Final verification and record-keeping responsibility lies with the taxpayer.

# Save the log to CSV
final_log.to_csv('irs_mileage_log.csv', index=False, encoding='utf-8-sig')
print("IRS-compliant mileage log saved as 'irs_mileage_log.csv'.")

Case Study / Example Calculation

Let's illustrate with a hypothetical scenario how the Python script works and how the final log is created.

Scenario

Tanaka, a freelance consultant, wants to claim business mileage deductions using Google Timeline data. His travel history for a particular day includes:

  • A trip from home to Client A's office.
  • A trip from Client A's office to Client B's office.
  • A trip from Client B's office to a restaurant for lunch.
  • A trip from the restaurant back home.

Processing with Python

  1. JSON Export: Tanaka exports his Google Timeline data for the past month via Google Takeout.
  2. Python Script Execution: The exported JSON file is fed into the Python script. The script identifies distinct travel segments and calculates the total distance for each.
  3. Trip Identification: The script segments Tanaka's travel into four parts:
    • Segment 1: Home → Client A Office
    • Segment 2: Client A Office → Client B Office
    • Segment 3: Client B Office → Restaurant
    • Segment 4: Restaurant → Home
  4. Initial Log Generation: The script produces a preliminary log showing start/end times, locations (approximate addresses via reverse geocoding if enabled), and total mileage for each segment.
  5. Manual Completion: Tanaka opens the generated log in a spreadsheet and fills in the `business_miles` and `purpose` for trips considered business-related:
    • Segment 1: Business purpose. Purpose: "Client A Visit". `business_miles` = total miles of Segment 1.
    • Segment 2: Business purpose. Purpose: "Client B Visit". `business_miles` = total miles of Segment 2.
    • Segment 3: Business purpose (client lunch). Purpose: "Lunch with Client B". `business_miles` = total miles of Segment 3.
    • Segment 4: Return home. Not business purpose. `business_miles` = 0.
  6. Final Log Saving: Tanaka saves the completed log as a CSV file for his tax return.

Calculation Example (Simplified)

Assume the script calculated the following distances:

  • Segment 1: 15.2 miles
  • Segment 2: 8.5 miles
  • Segment 3: 2.1 miles
  • Segment 4: 18.0 miles

After Tanaka's manual completion, the final mileage log looks like this:

Date Start Address End Address Total Miles Business Miles Purpose
2023-10-27 Home Address (approx.) Client A Office (approx.) 15.2 15.2 Client A Visit
2023-10-27 Client A Office (approx.) Client B Office (approx.) 8.5 8.5 Client B Visit
2023-10-27 Client B Office (approx.) Restaurant (approx.) 2.1 2.1 Lunch with Client B
2023-10-27 Restaurant (approx.) Home Address (approx.) 18.0 0.0 Return Home

In this case, Tanaka's total business mileage is 15.2 + 8.5 + 2.1 = 25.8 miles. This amount will be used to calculate his tax deduction.

Pros and Cons

Using Google Timeline data for mileage logging offers significant advantages but also comes with limitations.

Pros

  • Automated Recording: Reduces the burden of manual entry once set up.
  • Detailed Data: Provides granular information on routes and times based on GPS.
  • Centralized Management: Data is managed within your Google account.
  • Flexible Analysis: Python allows for custom data cleaning, transformation, and analysis tailored to IRS requirements.
  • Strong Evidence: Well-maintained digital logs can serve as robust evidence during IRS audits.

Cons

  • Privacy Concerns: Location tracking raises privacy issues; securing your Google account is crucial.
  • Accuracy Limitations: GPS accuracy can vary (indoors, urban canyons). Straight-line distance differs from actual road mileage.
  • Business Purpose Determination: Automatically determining business purpose is challenging and requires manual input, which is critical for IRS compliance.
  • Initial Setup Effort: Requires setting up Python, preparing data, and performing manual completion.
  • Battery Drain: Continuous location tracking can consume significant smartphone battery power.

Common Pitfalls and Considerations

Be aware of these common mistakes and important points:

  • Location History Disabled: Ensure location history is enabled in your Google account settings.
  • Incomplete Data Export: Verify that you have exported data for the entire relevant period.
  • Time Zone Errors: Incorrect handling of UTC vs. local time can lead to miscalculations.
  • Distance Discrepancies: Understand the difference between geodesic (as-the-crow-flies) and actual road mileage. The IRS typically prefers road mileage.
  • Inadequate Business Purpose Documentation: This is the most common failure point. Ensure each business trip is clearly documented with its purpose. Vague entries are risky.
  • Incorrectly Including Commuting Miles: Regular commuting is generally non-deductible.
  • Lack of Contemporaneous Records: The IRS prefers records kept at the time of the trip. Avoid logging large amounts of data long after the travel occurred.
  • Misunderstanding the Script: Use the Python script only after understanding how it processes data to avoid errors.
  • Over-reliance on Technology: Remember Google Timeline has limitations. Manual review and completion are essential for accuracy and compliance.

Frequently Asked Questions (FAQ)

Q1: How long is Google Timeline data retained, and are there limits on export duration?

A1: Data retention depends on your Google account settings, specifically the 'Auto-delete' option (e.g., 3, 18, 36 months, or 'Keep until I delete'). By default, it might be indefinite. Google Takeout allows exporting data for selected periods, typically spanning several years. However, exporting very large amounts of data at once might be slow or error-prone. It's often practical to export data in smaller chunks, such as yearly.

Q2: If the distance calculated by the Python script differs from my car's odometer reading, which should I use?

A2: The IRS requires accurate records. Ideally, your log should align with odometer readings. Script-calculated distances are approximations based on GPS and straight-line calculations. If you have odometer readings, prioritize them. Use the script's output as a reference for travel segments, or adjust the script's output to match your odometer readings. Alternatively, use the script for trip evidence and manually enter distances based on odometer records. Consistency and explainability are key.

Q3: Is Google Timeline data alone sufficient to meet IRS requirements?

A3: No, Google Timeline data alone is generally insufficient. While it captures factual movement data (when, where, how), it doesn't record the 'why' (business purpose) or the specific business mileage. This crucial information requires taxpayer input. The Python script assists in extracting and organizing travel data, but the final mileage log must be completed manually with trip purposes and accurate business mileage figures, ensuring the record's integrity and compliance.

Conclusion

Parsing Google Timeline JSON data with Python to create an IRS-compliant mileage log is an effective strategy to streamline record-keeping and maximize potential tax deductions. This article has covered the essential steps, from data preparation and Python parsing to identifying travel segments and the critical need for manual completion to meet IRS standards.

Implementing this method can save considerable time and effort while improving the accuracy and reliability of your records. However, it's vital to balance technological efficiency with a thorough understanding of IRS regulations and privacy considerations. Clearly documenting the business purpose of each trip remains the cornerstone of a compliant mileage log.

Remember, the Python script is a tool; the ultimate responsibility for accurate and compliant record-keeping rests with you, the taxpayer. By adapting the procedures and insights provided here to your specific situation, you can enhance your tax management practices effectively.

#Python #Google Timeline #IRS #Mileage Log #Tax Deduction #Record Keeping #Automation