Parses vCards into JSON, keeping the repeating fields as arrays rather than flattening them into numbered columns. This is the right shape when the destination is code rather than a spreadsheet.
Why arrays beat numbered columns here
The CSV version has to invent
Phone 1, Phone 2, Phone 3 because a table has fixed columns. JSON does not need to: phones is an array of {type, value}, however many there are.
Addresses stay structured too — {type, street, city, region, postcode, country} — rather than being split across six columns or crushed into one string.
Every key is present on every contact even when empty, so consuming code never has to guard against a missing field.
Structured names
vCard stores a name twice:
FN is the display form ("Ada Lovelace") and N is structured (family; given; middle; prefix; suffix). Both come across — formattedName and the five parts — because which one you want depends entirely on what you are doing, and reconstructing one from the other is unreliable across cultures.Contact photos are inside the file
vCard can embed a photograph directly, base64-encoded, in a
PHOTO property. One portrait from a phone can be larger than every other field in the export put together, which is why a contacts file of a few hundred people is sometimes tens of megabytes. Those come across as data URIs, so the JSON stays self-contained and can still be written straight to disk. If you only wanted the names and numbers, that is worth knowing before you paste the result somewhere with a size limit.Other names for this
Also searched as “vcard to json”, “parse vcf”.
Questions
- Are photos included?
- No. They are large Base64 blobs; keep the original .vcf if you need them.
- What if the file mixes vCard versions?
- All three versions are read and normalised into the same shape, and you are told the file was mixed.
- Is this safe for other people’s personal data?
- Uploading an address book to a third-party service is a disclosure of other people’s personal data, and under the GDPR that needs a lawful basis you almost certainly do not have. Nothing is transmitted here, so the question does not arise. Turn your Wi-Fi off and check.