GeoJSON

0.3.0 release

Welcome to the Open Fibre Data Standard 0.3.0 release.

We want to hear your feedback on the standard and its documentation. For general feedback, questions and suggestions, you can comment on an existing discussion or start a new one. For bug reports or feedback on specific elements of the data model and documentation, you can comment on the issues in the issue tracker or you can create a new issue.

To comment on or create discussions and issues, you need to sign up for a free GitHub account. If you prefer to provide feedback privately, you can email info@opentelecomdata.net.

This page describes how to publish data in GeoJSON format.

If your data is small enough to fit into memory or if you are publishing data via an API, you should use the small files and API responses option. If your data is too large to fit into memory, you should use the streaming option.

Some GIS tools require all features in a GeoJSON feature collection to have the same .geometry.type or to have a consistent schema of .properties. Therefore, in order to reduce barriers for users of such tools, the recommended approach is to publish separate feature collections for nodes and spans. If you prefer, you may publish a single feature collection containing both nodes and spans. In which case, the properties.featureType field can be used to determine whether each feature is a node or a span.

Small files and API responses option

You should publish separate GeoJSON feature collections for nodes and spans, according to the GeoJSON transformation specification.

Nodes feature collection

The following example shows a GeoJSON feature collection containing nodes:

{
    "type": "FeatureCollection",
    "features": [
        {
            "type": "Feature",
            "geometry": {
                "type": "Point",
                "coordinates": [
                    -0.174,
                    5.625
                ]
            },
            "properties": {
                "id": "1",
                "name": "Accra",
                "phase": {
                    "id": "1",
                    "name": "NextGen Phase 1",
                    "description": "The first phase of the Ghana Fibre Network NextGen roll-out.",
                    "funders": [
                        {
                            "id": "1",
                            "name": "Ghana Infrastructure Investment Fund",
                            "country": "GH",
                            "roles": [
                                "funder"
                            ],
                            "roleDetails": "The Ghana Infrastructure Investment Fund provided equity financing for the construction of phase 1 of the NextGen network.",
                            "website": "https://www.example.com",
                            "logo": "https://www.example.com/logo.png"
                        }
                    ]
                },
                "status": "operational",
                "address": {
                    "streetAddress": "Boundary Rd",
                    "locality": "Shiashie",
                    "region": "Accra",
                    "postalCode": "12345",
                    "country": "GH"
                },
                "type": [
                    "pop"
                ],
                "accessPoint": true,
                "internationalConnections": [
                    {
                        "region": "Lom\u00e9",
                        "country": "TG"
                    }
                ],
                "power": true,
                "technologies": [
                    "ip"
                ],
                "physicalInfrastructureProvider": {
                    "id": "GH-RGD-CS111111111",
                    "name": "FibreCo",
                    "identifier": {
                        "id": "CS111111111",
                        "scheme": "GH-RGD",
                        "legalName": "FibreCo Ghana Limited",
                        "uri": "https://example.com/companies/CS111111111"
                    },
                    "country": "GH",
                    "roles": [
                        "physicalInfrastructureProvider"
                    ],
                    "roleDetails": "FibreCo owns and maintains the physical infrastructure.",
                    "website": "https://www.example.com",
                    "logo": "https://www.example.com/logo.png"
                },
                "networkProviders": [
                    {
                        "id": "GH-RGD-CS222222222",
                        "name": "FastWeb",
                        "identifier": {
                            "id": "CS222222222",
                            "scheme": "GH-RGD",
                            "legalName": "FastWeb Ghana Limited",
                            "uri": "https://example.com/companies/CS222222222"
                        },
                        "country": "GH",
                        "roles": [
                            "networkProvider"
                        ],
                        "roleDetails": "FastWeb provides wholesale services to service providers and dark fibre access to other network providers.",
                        "website": "https://www.example.com",
                        "logo": "https://www.example.com/logo.png"
                    }
                ],
                "network": {
                    "id": "a096d627-72e1-4f9b-b129-951b1737bff4",
                    "name": "Ghana Fibre Network",
                    "contracts": [
                        {
                            "id": "1",
                            "title": "NextGen Phase 1 Construction Contract",
                            "description": "Contract for the construction of phase 1 of the NextGen network.",
                            "type": "private",
                            "value": {
                                "amount": 1537459500.0,
                                "currency": "GHS"
                            },
                            "dateSigned": "2016-06-30",
                            "documents": [
                                {
                                    "title": "NextGen Phase 1 Construction Contract",
                                    "description": "Signed contract.",
                                    "url": "http://example.com/contracts/nextgen-phase1-construction.pdf",
                                    "format": "application/pdf"
                                }
                            ],
                            "relatedPhases": [
                                {
                                    "id": "1",
                                    "name": "NextGen Phase 1",
                                    "description": "The first phase of the Ghana Fibre Network NextGen roll-out.",
                                    "funders": [
                                        {
                                            "id": "1",
                                            "name": "Ghana Infrastructure Investment Fund",
                                            "country": "GH",
                                            "roles": [
                                                "funder"
                                            ],
                                            "roleDetails": "The Ghana Infrastructure Investment Fund provided equity financing for the construction of phase 1 of the NextGen network.",
                                            "website": "https://www.example.com",
                                            "logo": "https://www.example.com/logo.png"
                                        }
                                    ]
                                }
                            ]
                        }
                    ],
                    "website": "http://example.com/network",
                    "publisher": {
                        "name": "FibreCo",
                        "identifier": {
                            "id": "CS111111111",
                            "scheme": "GH-RGD",
                            "legalName": "FibreCo Ghana Limited",
                            "uri": "https://example.com/companies/CS111111111"
                        }
                    },
                    "publicationDate": "2022-01-01",
                    "collectionDate": "2021-09-30",
                    "crs": {
                        "name": "urn:ogc:def:crs:OGC::CRS84",
                        "uri": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
                    },
                    "accuracy": 250,
                    "accuracyDetails": "Measured according to the US National Standard for Spatial Data Accuracy.",
                    "language": "en",
                    "links": [
                        {
                            "rel": "describedby",
                            "href": "https://raw.githubusercontent.com/Open-Telecoms-Data/open-fibre-data-standard/0__3__0/schema/network-schema.json"
                        }
                    ]
                },
                "featureType": "node"
            }
        },
        {
            "type": "Feature",
            "geometry": {
                "type": "Point",
                "coordinates": [
                    -1.628,
                    6.711
                ]
            },
            "properties": {
                "id": "2",
                "name": "Kumasi",
                "phase": {
                    "id": "1",
                    "name": "NextGen Phase 1",
                    "description": "The first phase of the Ghana Fibre Network NextGen roll-out.",
                    "funders": [
                        {
                            "id": "1",
                            "name": "Ghana Infrastructure Investment Fund",
                            "country": "GH",
                            "roles": [
                                "funder"
                            ],
                            "roleDetails": "The Ghana Infrastructure Investment Fund provided equity financing for the construction of phase 1 of the NextGen network.",
                            "website": "https://www.example.com",
                            "logo": "https://www.example.com/logo.png"
                        }
                    ]
                },
                "status": "operational",
                "address": {
                    "streetAddress": "Kejetia Road",
                    "locality": "Bantama",
                    "region": "Kumasi",
                    "postalCode": "00000",
                    "country": "GH"
                },
                "type": [
                    "pop"
                ],
                "accessPoint": false,
                "power": true,
                "technologies": [
                    "ip"
                ],
                "physicalInfrastructureProvider": {
                    "id": "GH-RGD-CS111111111",
                    "name": "FibreCo",
                    "identifier": {
                        "id": "CS111111111",
                        "scheme": "GH-RGD",
                        "legalName": "FibreCo Ghana Limited",
                        "uri": "https://example.com/companies/CS111111111"
                    },
                    "country": "GH",
                    "roles": [
                        "physicalInfrastructureProvider"
                    ],
                    "roleDetails": "FibreCo owns and maintains the physical infrastructure.",
                    "website": "https://www.example.com",
                    "logo": "https://www.example.com/logo.png"
                },
                "networkProviders": [
                    {
                        "id": "GH-RGD-CS222222222",
                        "name": "FastWeb",
                        "identifier": {
                            "id": "CS222222222",
                            "scheme": "GH-RGD",
                            "legalName": "FastWeb Ghana Limited",
                            "uri": "https://example.com/companies/CS222222222"
                        },
                        "country": "GH",
                        "roles": [
                            "networkProvider"
                        ],
                        "roleDetails": "FastWeb provides wholesale services to service providers and dark fibre access to other network providers.",
                        "website": "https://www.example.com",
                        "logo": "https://www.example.com/logo.png"
                    }
                ],
                "network": {
                    "id": "a096d627-72e1-4f9b-b129-951b1737bff4",
                    "name": "Ghana Fibre Network",
                    "contracts": [
                        {
                            "id": "1",
                            "title": "NextGen Phase 1 Construction Contract",
                            "description": "Contract for the construction of phase 1 of the NextGen network.",
                            "type": "private",
                            "value": {
                                "amount": 1537459500.0,
                                "currency": "GHS"
                            },
                            "dateSigned": "2016-06-30",
                            "documents": [
                                {
                                    "title": "NextGen Phase 1 Construction Contract",
                                    "description": "Signed contract.",
                                    "url": "http://example.com/contracts/nextgen-phase1-construction.pdf",
                                    "format": "application/pdf"
                                }
                            ],
                            "relatedPhases": [
                                {
                                    "id": "1",
                                    "name": "NextGen Phase 1",
                                    "description": "The first phase of the Ghana Fibre Network NextGen roll-out.",
                                    "funders": [
                                        {
                                            "id": "1",
                                            "name": "Ghana Infrastructure Investment Fund",
                                            "country": "GH",
                                            "roles": [
                                                "funder"
                                            ],
                                            "roleDetails": "The Ghana Infrastructure Investment Fund provided equity financing for the construction of phase 1 of the NextGen network.",
                                            "website": "https://www.example.com",
                                            "logo": "https://www.example.com/logo.png"
                                        }
                                    ]
                                }
                            ]
                        }
                    ],
                    "website": "http://example.com/network",
                    "publisher": {
                        "name": "FibreCo",
                        "identifier": {
                            "id": "CS111111111",
                            "scheme": "GH-RGD",
                            "legalName": "FibreCo Ghana Limited",
                            "uri": "https://example.com/companies/CS111111111"
                        }
                    },
                    "publicationDate": "2022-01-01",
                    "collectionDate": "2021-09-30",
                    "crs": {
                        "name": "urn:ogc:def:crs:OGC::CRS84",
                        "uri": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
                    },
                    "accuracy": 250,
                    "accuracyDetails": "Measured according to the US National Standard for Spatial Data Accuracy.",
                    "language": "en",
                    "links": [
                        {
                            "rel": "describedby",
                            "href": "https://raw.githubusercontent.com/Open-Telecoms-Data/open-fibre-data-standard/0__3__0/schema/network-schema.json"
                        }
                    ]
                },
                "featureType": "node"
            }
        }
    ]
}

Spans feature collection

The following example shows a GeoJSON feature collection containing spans:

{
    "type": "FeatureCollection",
    "features": [
        {
            "type": "Feature",
            "geometry": {
                "type": "LineString",
                "coordinates": [
                    [
                        -0.173,
                        5.626
                    ],
                    [
                        -0.178,
                        5.807
                    ],
                    [
                        -0.112,
                        5.971
                    ],
                    [
                        -0.211,
                        5.963
                    ],
                    [
                        -0.321,
                        6.17
                    ],
                    [
                        -0.488,
                        6.29
                    ],
                    [
                        -0.56,
                        6.421
                    ],
                    [
                        -0.752,
                        6.533
                    ],
                    [
                        -0.867,
                        6.607
                    ],
                    [
                        -1.101,
                        6.585
                    ],
                    [
                        -1.304,
                        6.623
                    ],
                    [
                        -1.461,
                        6.727
                    ],
                    [
                        -1.628,
                        6.713
                    ]
                ]
            },
            "properties": {
                "id": "1",
                "name": "Accra to Kumasi",
                "phase": {
                    "id": "1",
                    "name": "NextGen Phase 1",
                    "description": "The first phase of the Ghana Fibre Network NextGen roll-out.",
                    "funders": [
                        {
                            "id": "1",
                            "name": "Ghana Infrastructure Investment Fund",
                            "country": "GH",
                            "roles": [
                                "funder"
                            ],
                            "roleDetails": "The Ghana Infrastructure Investment Fund provided equity financing for the construction of phase 1 of the NextGen network.",
                            "website": "https://www.example.com",
                            "logo": "https://www.example.com/logo.png"
                        }
                    ]
                },
                "status": "operational",
                "readyForServiceDate": "2018-01-01",
                "start": {
                    "id": "1",
                    "name": "Accra",
                    "phase": {
                        "id": "1",
                        "name": "NextGen Phase 1"
                    },
                    "status": "operational",
                    "location": {
                        "type": "Point",
                        "coordinates": [
                            -0.174,
                            5.625
                        ]
                    },
                    "address": {
                        "streetAddress": "Boundary Rd",
                        "locality": "Shiashie",
                        "region": "Accra",
                        "postalCode": "12345",
                        "country": "GH"
                    },
                    "type": [
                        "pop"
                    ],
                    "accessPoint": true,
                    "internationalConnections": [
                        {
                            "region": "Lom\u00e9",
                            "country": "TG"
                        }
                    ],
                    "power": true,
                    "technologies": [
                        "ip"
                    ],
                    "physicalInfrastructureProvider": {
                        "id": "GH-RGD-CS111111111",
                        "name": "FibreCo"
                    },
                    "networkProviders": [
                        {
                            "id": "GH-RGD-CS222222222",
                            "name": "FastWeb"
                        }
                    ]
                },
                "end": {
                    "id": "2",
                    "name": "Kumasi",
                    "phase": {
                        "id": "1",
                        "name": "NextGen Phase 1"
                    },
                    "status": "operational",
                    "location": {
                        "type": "Point",
                        "coordinates": [
                            -1.628,
                            6.711
                        ]
                    },
                    "address": {
                        "streetAddress": "Kejetia Road",
                        "locality": "Bantama",
                        "region": "Kumasi",
                        "postalCode": "00000",
                        "country": "GH"
                    },
                    "type": [
                        "pop"
                    ],
                    "accessPoint": false,
                    "power": true,
                    "technologies": [
                        "ip"
                    ],
                    "physicalInfrastructureProvider": {
                        "id": "GH-RGD-CS111111111",
                        "name": "FibreCo"
                    },
                    "networkProviders": [
                        {
                            "id": "GH-RGD-CS222222222",
                            "name": "FastWeb"
                        }
                    ]
                },
                "directed": false,
                "physicalInfrastructureProvider": {
                    "id": "GH-RGD-CS111111111",
                    "name": "FibreCo",
                    "identifier": {
                        "id": "CS111111111",
                        "scheme": "GH-RGD",
                        "legalName": "FibreCo Ghana Limited",
                        "uri": "https://example.com/companies/CS111111111"
                    },
                    "country": "GH",
                    "roles": [
                        "physicalInfrastructureProvider"
                    ],
                    "roleDetails": "FibreCo owns and maintains the physical infrastructure.",
                    "website": "https://www.example.com",
                    "logo": "https://www.example.com/logo.png"
                },
                "networkProviders": [
                    {
                        "id": "GH-RGD-CS222222222",
                        "name": "FastWeb",
                        "identifier": {
                            "id": "CS222222222",
                            "scheme": "GH-RGD",
                            "legalName": "FastWeb Ghana Limited",
                            "uri": "https://example.com/companies/CS222222222"
                        },
                        "country": "GH",
                        "roles": [
                            "networkProvider"
                        ],
                        "roleDetails": "FastWeb provides wholesale services to service providers and dark fibre access to other network providers.",
                        "website": "https://www.example.com",
                        "logo": "https://www.example.com/logo.png"
                    }
                ],
                "supplier": {
                    "id": "GH-RGD-CS333333333",
                    "name": "ProjectCo"
                },
                "transmissionMedium": [
                    "fibre"
                ],
                "deployment": [
                    "belowGround"
                ],
                "deploymentDetails": {
                    "description": "Buried in ducts"
                },
                "darkFibre": true,
                "fibreType": "G.652",
                "fibreTypeDetails": {
                    "fibreSubtype": "G.652.D",
                    "description": "CABLED STANDARD ENHANCED SINGLEMODE FIBRE ESMF, LOW WATER PEAK SINGLE MODE FIBRE G.652.D, OS2"
                },
                "fibreCount": 24,
                "fibreLength": 276000,
                "technologies": [
                    "sdh"
                ],
                "capacity": 4.976,
                "capacityDetails": {
                    "description": "2xSTM-16"
                },
                "countries": [
                    "GH"
                ],
                "network": {
                    "id": "a096d627-72e1-4f9b-b129-951b1737bff4",
                    "name": "Ghana Fibre Network",
                    "contracts": [
                        {
                            "id": "1",
                            "title": "NextGen Phase 1 Construction Contract",
                            "description": "Contract for the construction of phase 1 of the NextGen network.",
                            "type": "private",
                            "value": {
                                "amount": 1537459500.0,
                                "currency": "GHS"
                            },
                            "dateSigned": "2016-06-30",
                            "documents": [
                                {
                                    "title": "NextGen Phase 1 Construction Contract",
                                    "description": "Signed contract.",
                                    "url": "http://example.com/contracts/nextgen-phase1-construction.pdf",
                                    "format": "application/pdf"
                                }
                            ],
                            "relatedPhases": [
                                {
                                    "id": "1",
                                    "name": "NextGen Phase 1",
                                    "description": "The first phase of the Ghana Fibre Network NextGen roll-out.",
                                    "funders": [
                                        {
                                            "id": "1",
                                            "name": "Ghana Infrastructure Investment Fund",
                                            "country": "GH",
                                            "roles": [
                                                "funder"
                                            ],
                                            "roleDetails": "The Ghana Infrastructure Investment Fund provided equity financing for the construction of phase 1 of the NextGen network.",
                                            "website": "https://www.example.com",
                                            "logo": "https://www.example.com/logo.png"
                                        }
                                    ]
                                }
                            ]
                        }
                    ],
                    "website": "http://example.com/network",
                    "publisher": {
                        "name": "FibreCo",
                        "identifier": {
                            "id": "CS111111111",
                            "scheme": "GH-RGD",
                            "legalName": "FibreCo Ghana Limited",
                            "uri": "https://example.com/companies/CS111111111"
                        }
                    },
                    "publicationDate": "2022-01-01",
                    "collectionDate": "2021-09-30",
                    "crs": {
                        "name": "urn:ogc:def:crs:OGC::CRS84",
                        "uri": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
                    },
                    "accuracy": 250,
                    "accuracyDetails": "Measured according to the US National Standard for Spatial Data Accuracy.",
                    "language": "en",
                    "links": [
                        {
                            "rel": "describedby",
                            "href": "https://raw.githubusercontent.com/Open-Telecoms-Data/open-fibre-data-standard/0__3__0/schema/network-schema.json"
                        }
                    ]
                },
                "featureType": "span"
            }
        }
    ]
}

Each feature collection may contain features from one or more networks. The network each feature relates to is identified by its .properties.network.id.

The following example shows a GeoJSON feature collection containing features from two networks:

{
    "type": "FeatureCollection",
    "features": [
        {
            "type": "Feature",
            "properties": {
                "id": "1",
                "name": "Accra POP",
                "network": {
                    "id": "fd7b30d6-f514-4cd0-a5ac-29a774f53a43",
                    "name": "Ghana Fibre Network"
                },
                "featureType": "node"
            }
        },
        {
            "type": "Feature",
            "properties": {
                "id": "1",
                "name": "Lom\u00e9 POP",
                "network": {
                    "id": "acafe566-7ffa-416a-b3b4-84a52386a586",
                    "name": "Togo Fibre Network"
                },
                "featureType": "node"
            }
        }
    ]
}

For data published via a paginated API, you should add a top-level links object to the feature collection to provide URLs for the next and previous pages of results:

Links object schema

Title	Description	Type	Format	Required
next		string	iri
Next	A URL to the next sequential package.
prev		string	iri
Previous	A URL to the previous sequential package.

API response example

The following example shows a GeoJSON feature collection containing two features with URLS for the next and previous pages of results.

{
    "type": "FeatureCollection",
    "features": [
        {
            "type": "Feature",
            "properties": {
                "id": "1",
                "name": "Accra POP",
                "network": {
                    "id": "fd7b30d6-f514-4cd0-a5ac-29a774f53a43",
                    "name": "Ghana Fibre Network"
                },
                "featureType": "node"
            }
        },
        {
            "type": "Feature",
            "properties": {
                "id": "2",
                "name": "Kumasi POP",
                "network": {
                    "id": "fd7b30d6-f514-4cd0-a5ac-29a774f53a43",
                    "name": "Ghana Fibre Network"
                },
                "featureType": "node"
            }
        }
    ],
    "links": {
        "next": "http://example.com/nodes?cursor=100",
        "prev": "http://example.com/nodes?cursor=96"
    }
}

Streaming option

The streaming option describes how to publish multiple networks in GeoJSON format with support for streaming. You should only use this option if your data is too large to load into memory.

You should publish separate Newline-delimited GeoJSON files for nodes and spans, in which each line is a GeoJSON feature structured according to the GeoJSON transformation specification.

The following example shows a newline-delimited GeoJSON file containing two nodes:

{"type":"Feature","properties":{"id":"1","name":"Accra POP","network":{"id":"fd7b30d6-f514-4cd0-a5ac-29a774f53a43","name":"Ghana Fibre Network"}, "featureType": "node"}}
{"type":"Feature","properties":{"id":"2","name":"Kumasi POP","network":{"id":"fd7b30d6-f514-4cd0-a5ac-29a774f53a43","name":"Ghana Fibre Network"}, "featureType": "node"}}

GeoJSON transformation specification

This section describes the rules for transforming an OFDS network from JSON format to GeoJSON format.

The transformation specification describes the recommended approach of producing separate feature collections for nodes and spans. If you prefer to publish a single GeoJSON feature collection containing both nodes and spans, you may combine the the resulting feature collections into a single feature collection.

• Create an empty JSON object for the nodes feature collection and set its .type to ‘FeatureCollection’.

• Create an empty JSON object for the spans feature collection and set its .type to ‘FeatureCollection’.

• For each contract in contracts, dereference the phase references in .relatedPhases.

• For each node in nodes:

  • Convert the node to a GeoJSON feature:

    • Create an empty JSON object for the feature.

    • Set the feature’s:

    • .type to ‘Feature’.

    • .geometry to the node’s .location, if it exists. Otherwise, set .geometry to Null.

    • .properties to the properties of the node, excluding .location.

    • .properties.featureType to ‘node’.

    • Dereference the organisation references in .properties.physicalInfrastructureProvider and .networkProviders.

    • Dereference the phase reference in the feature’s .phase property.

    • Set .properties.network to the properties of the network, excluding .nodes, .spans, .phases and .organisations.

  • Add the feature to the nodes feature collection.

• For each span in spans:

  • Convert the span to a GeoJSON Feature:

    • Create an empty JSON object for the feature.

    • Set the feature’s:

    • .type to ‘Feature’.

    • .geometry to the span’s .route, if it exists. Otherwise, set .geometry to Null.

    • .properties to the properties of the span, excluding .route.

    • .properties.featureType to ‘span’.

    • Dereference the organisation references in .properties.physicalInfrastructureProvider and .networkProviders.

    • Dereference the phase reference in .properties.phase.

    • Dereference the node ids in properties.start and properties.end.

    • Set .properties.network to the properties of the network, excluding .nodes, .spans, .phases and .organisations.

  • Add the feature to the spans feature collection.

Common operations

Dereference an organisation reference

Get the Organisation object in organisations whose .id is equal to the .id of the OrganizationReference.

Dereference a phase reference

Get the Phase object in phases whose .id is equal to the id of the PhaseReference.

Dereference a node ID

Get the Node object in nodes whose .id is equal to the ID.

Reference implementation

A reference implementation of the transformation is available in Python on Github. We strongly encourage any re-implementations to read its commented code, to ensure correctness.