CSVJSON(1)

🌸 NAME 🌸

okay bestie, meet csvjson — it's a lil tool from the csvkit family (manual section 1, yes she's official 💅) and she converts your CSV into JSON or GeoJSON depending on which flags you throw at her. That's the whole vibe.

---

✨ DESCRIPTION ✨

Converts a CSV file into JSON or GeoJSON (depending on flags) 🦋

Like, literally here's the usage, character for character, no cap:

usage: csvjson [-h] [-d DELIMITER] [-t] [-q QUOTECHAR] [-u {0,1,2,3}] [-b]
               [-p ESCAPECHAR] [-z FIELD_SIZE_LIMIT] [-e ENCODING] [-L LOCALE]
               [-S] [--blanks] [--null-value NULL_VALUES [NULL_VALUES ...]]
               [--date-format DATE_FORMAT] [--datetime-format DATETIME_FORMAT]
               [-H] [-K SKIP_LINES] [-v] [-l] [--zero] [-V] [-i INDENT]
               [-k KEY] [--lat LAT] [--lon LON] [--type TYPE]
               [--geometry GEOMETRY] [--crs CRS] [--no-bbox] [--stream]
               [-y SNIFF_LIMIT] [-I]
               [FILE]

Convert a CSV file into JSON (or GeoJSON).

positional arguments:
  FILE                  The CSV file to operate on. If omitted, will accept
                        input as piped data via STDIN.

optional arguments:
  -h, --help            show this help message and exit
  -i INDENT, --indent INDENT
                        Indent the output JSON this many spaces. Disabled by
                        default.
  -k KEY, --key KEY     Output JSON as an object keyed by a given column, KEY,
                        rather than as an array. All column values must be
                        unique. If --lat and --lon are specified, this column
                        is used as the GeoJSON Feature ID.
  --lat LAT             A column index or name containing a latitude. Output
                        will be GeoJSON instead of JSON. Requires --lon.
  --lon LON             A column index or name containing a longitude. Output
                        will be GeoJSON instead of JSON. Requires --lat.
  --type TYPE           A column index or name containing a GeoJSON type.
                        Output will be GeoJSON instead of JSON. Requires --lat
                        and --lon.
  --geometry GEOMETRY   A column index or name containing a GeoJSON geometry.
                        Output will be GeoJSON instead of JSON. Requires --lat
                        and --lon.
  --crs CRS             A coordinate reference system string to be included
                        with GeoJSON output. Requires --lat and --lon.
  --no-bbox             Disable the calculation of a bounding box.
  --stream              Output JSON as a stream of newline-separated objects,
                        rather than an as an array.
  -y SNIFF_LIMIT, --snifflimit SNIFF_LIMIT
                        Limit CSV dialect sniffing to the specified number of
                        bytes. Specify "0" to disable sniffing entirely, or
                        "-1" to sniff the entire file.
  -I, --no-inference    Disable type inference (and --locale, --date-format,
                        --datetime-format, --no-leading-zeroes) when parsing
                        the input.

---

🎀 OPTIONS 🎀

bestie here's every single flag, i did NOT skip a single one, we're thorough in this house 🫶

• -h, --help — shows this help message and dips. that's it, that's the flag ✨
• -i INDENT, --indent INDENT — indents the output JSON by this many spaces. off by default, so if you want pretty-printed JSON you gotta ask nicely 💅
• -k KEY, --key KEY — outputs JSON as an object keyed by the given column, KEY, instead of as an array. every value in that column has to be unique or it's not gonna fly. and ooh — if you also pass --lat and --lon, that column becomes the GeoJSON Feature ID 👑
• --lat LAT — a column index or name holding a latitude. the output becomes GeoJSON instead of plain JSON. requires --lon or it's a no-go 🚫
• --lon LON — a column index or name holding a longitude. output becomes GeoJSON instead of JSON. requires --lat, same deal 🚫
• --type TYPE — a column index or name holding a GeoJSON type. output becomes GeoJSON instead of JSON. requires --lat and --lon — both of them, periodt
• --geometry GEOMETRY — a column index or name holding a GeoJSON geometry. output becomes GeoJSON instead of JSON. requires --lat and --lon — yeah, both
• --crs CRS — a coordinate reference system string to be included with GeoJSON output. requires --lat and --lon 🌈
• --no-bbox — disables the calculation of a bounding box. if you don't want that bbox energy, this is your girl
• --stream — outputs JSON as a stream of newline-separated objects rather than as an array. streamer era 💀
• -y SNIFF_LIMIT, --snifflimit SNIFF_LIMIT — limits CSV dialect sniffing to the specified number of bytes. specify "0" to disable sniffing entirely, or "-1" to sniff the entire file 🐽
• -I, --no-inference — disables type inference (and --locale, --date-format, --datetime-format, --no-leading-zeroes) when parsing the input. no guessing, just vibes 🧚

Also worth knowing, fr fr: See also: Arguments common to all tools. — those are shared across the whole csvkit crew, so go check 'em out 💖

---

🦋 EXAMPLES 🦋

🌸 Convert veteran's education dataset to JSON keyed by state abbreviation:

$ csvjson -k "State Abbreviate" -i 4 examples/realdata/FY09_EDU_Recipients_by_State.csv
{
    "AL": {
        "State Name": "ALABAMA",
        "State Abbreviate": "AL",
        "Code": 1.0,
        "Montgomery GI Bill-Active Duty": 6718.0,
        "Montgomery GI Bill- Selective Reserve": 1728.0,
        "Dependents' Educational Assistance": 2703.0,
        "Reserve Educational Assistance Program": 1269.0,
        "Post-Vietnam Era Veteran's Educational Assistance Program": 8.0,
        "TOTAL": 12426.0,
        "j": null
    },
    "...": {
        "...": "..."
    }
}

🗺️ Convert locations of public art into GeoJSON:

$ csvjson --lat latitude --lon longitude --k slug --crs EPSG:4269 -i 4 examples/test_geo.csv
{
    "type": "FeatureCollection",
    "bbox": [
        -95.334619,
        32.299076986939205,
        -95.250699,
        32.351434
    ],
    "crs": {
        "type": "name",
        "properties": {
            "name": "EPSG:4269"
        }
    },
    "features": [
        {
            "type": "Feature",
            "id": "dcl",
            "geometry": {
                "type": "Point",
                "coordinates": [
                    -95.30181,
                    32.35066
                ]
            },
            "properties": {
                "title": "Downtown Coffee Lounge",
                "artist": null,
                "description": "In addition to being the only coffee shop in downtown Tyler, DCL also features regular exhibitions of work by local artists.",
                "install_date": null,
                "address": "200 West Erwin Street",
                "type": "Gallery",
                "photo_url": null,
                "photo_credit": null,
                "last_seen_date": "2012-03-30"
            }
        },
        {
            "...": "..."
        }
    ],
    "crs": {
        "type": "name",
        "properties": {
            "name": "EPSG:4269"
        }
    }
}

---

💜 AUTHOR 💜

Christopher Groskopf and contributors — icons, every single one of them 👑

---

🌈 COPYRIGHT 🌈

2016, Christopher Groskopf and James McKinney

---

okay bestie that's the whole page 🫶 this is csvkit version 2.2.0, dated Aug 16, 2024, and it's giving CSVJSON(1) ✨ go forth and convert, you're gonna slay 💅🎀