Documentation feedback

[PVDL23]

I wanted to start by saying thank you to the maintainers of this package for all their hard work. As a Julia user with some experience, I found this package to be really useful, but I did encounter a few areas where the documentation could be improved from a user perspective.

I had a few issues when trying to create a Point (but also would have had them with the other geometry types). The documentation mentions these types, but it's not entirely clear how to create them. For example, I had to dig into the source code to figure out that I needed to create a Point like this: GeoJSON.Point(coordinates=(lon, lat)). As someone familiar with Julia, I eventually realised that this is consistent with how structs are typically constructed in Julia, but I can imagine that it might not be immediately obvious to users who are new to the language or the package. I think it would be really helpful to have some examples in the documentation on how to create these geometries, which would make it easier for users to get started with the package.

I also had an issue with the 'properties' keyword in the Feature type. The documentation says it should be a Union{Nothing,Dict{String,Any}}, but when I tried to create a Dict with string keys, I got an error. It turns out that the keys need to be Symbols, like this: props = Dict(:name => name, :locality => locality). I think it would be helpful to note this in the documentation, maybe I made a mistake or maybe this is a bug? Here is the error code just in case:

# with 
#     props = Dict(
#        "name" => name,
#        "locality" => locality
#    )

# it returns:
ERROR: LoadError: MethodError: Cannot `convert` an object of type String to an object of type Symbol
The function `convert` exists, but no method is defined for this combination of argument types.

Closest candidates are:
  Symbol(::String)
   @ Core boot.jl:618
  Symbol(::AbstractString)
   @ Base strings/basic.jl:228
  Symbol(::Any...)
   @ Base strings/basic.jl:229
  ...

Stacktrace:
 [1] setindex!(h::Dict{Symbol, Any}, v0::String, key0::String)
   @ Base ./dict.jl:346
 [2] Dict{Symbol, Any}(kv::Dict{String, String})
   @ Base ./dict.jl:94
 [3] convert
   @ ./abstractdict.jl:574 [inlined]
 [4] convert
   @ ./some.jl:37 [inlined]
 [5] Feature
   @ ~/.julia/packages/GeoJSON/0SijB/src/geojson_types.jl:170 [inlined]
 [6] #Feature#24
   @ ~/.julia/packages/GeoJSON/0SijB/src/geojson_types.jl:173 [inlined]
 [7] top-level scope
   @ /workspaces/julia/parse_stations.jl:21
in expression starting at /workspaces/julia/parse_stations.jl:8

Finally, I found it a bit tricky to create a Feature or FeatureCollection. I think it would be really helpful to have some examples in the documentation on how to create these types, including any required constructors.

I hope these suggestions are helpful. I'm really grateful for this package and I think with a few tweaks to the documentation, it could be even more beginner-friendly. Thanks again to the maintainers for all their hard work!

If there's anything I can do to help with implementing these changes or improving the documentation, please let me know.

[PVDL23]

Just in case:

Here is a snippet of stations.json:

{
    "meta": {
        "name": "openaq-api"
    },
    "results": [
        {
            "name": "Wekerom-Riemterdijk",
            "locality": "Wekerom",
            "coordinates": {
                "latitude": 52.111599999999996,
                "longitude": 5.70842
            }
        }
    ]
}

And here is the code that I wrote. Maybe I am doing some weird things but this is the version I got working:

using GeoJSON
using JSON3
using GeometryBasics # could have removed it but now the line numbers match the error message sent earlier

data = JSON3.read("stations.json")

features = GeoJSON.Feature{2, Float64}[]
for result in data.results
    lat::Float64 = result.coordinates.latitude
    lon::Float64 = result.coordinates.longitude
    name = result.name
    locality = result.locality

    # Create GeoJSON point feature with properties
    point = GeoJSON.Point(coordinates=(lon, lat))
    props = Dict(
        :name => name,
        :locality => locality
    )

    f = GeoJSON.Feature(
        geometry=point,
        properties=props
    )

    push!(features, f)
end

fc = GeoJSON.FeatureCollection{2, Float64}(;
    features = features
)

GeoJSON.write("stations.geojson", fc)

[rafaqz]

Just fixing the docs and making a PR is usually the most efficient path here! Probably String was used in the past.

As for creating geometries/features there is no real reason to use GeoJSON geoms specifically, you could use GeometryBasics or GeoInterface geometries in GeoInterface.jl Feature/FeatureCollection and they write to JSON just the same.

But likely we need some docs saying that too.

[PVDL23]

Thank you for the response. I'll create a PR for this and make some updates on the documentation