jupiter-to-contacts

Convert Excel contact spreadsheets to Google Contacts CSV format.

Installation

pip install -r requirements.txt

Optional (editable install with dev tools):

pip install -e '.[dev]'

Usage

Command Line

# Default: reads ./examples/excel.xlsx, writes ./examples/google_contacts.csv
python main.py

# Custom paths and country
python main.py -i contacts.xlsx -o output.csv -c US

The default input ./examples/excel.xlsx is not shipped with the repository (data files are gitignored) — create it or pass -i <path>.

As a Python Module

from jupiter_to_contacts import convert_excel_to_google_csv

convert_excel_to_google_csv("input.xlsx", "output.csv", default_country="IT")

Using Individual Functions

from jupiter_to_contacts.phone import format_phone_number, get_country_code

# Format a phone number
formatted = format_phone_number("+39 333 1234567", "Italy", "IT")

# Get country code from country name
code = get_country_code("Italy")  # Returns "IT"

To track numbers that could not be parsed, use PhoneNumberHandler directly:

from jupiter_to_contacts.phone import PhoneNumberHandler

handler = PhoneNumberHandler()
formatted = handler.format_phone_number("12345", "Italy")  # '' when unparseable
handler.get_failed_numbers()  # {('12345', 'Italy', 'IT')}

Input Format

The Excel file should contain columns for:

• First Name
• Last Name
• Email
• Phone (optional)
• WhatsApp (optional)
• Country (optional, defaults to IT)
• Birthdate (optional, DD/MM/YYYY)

Sheets with the required columns become contact groups in Google Contacts; sheets missing First Name, Last Name or Email are skipped.

Output

The output is a CSV file compatible with Google Contacts import.

Requirements

• Python 3.8+
• pandas
• phonenumbers
• openpyxl