JSON and GeoJSON

Understand the differences between GeoJSON and JSON for map visualizations in the Polyteia Platform.

To use a map visualization in the Polyteia Platform, your data must contain geographic shapes. These are described in a format called GeoJSON, a geographic version of JSON.

Other geographic shape data types like shape files will follow in future releases.

What is JSON

JSON (JavaScript Object Notation) is a common format for storing and exchanging data between systems. It's made up of key-value pairs and can include numbers, text, lists, and nested structures.

Here's a simple example:

[
  {
    "city": "Berlin",
    "population": 3769000,
    "isCapital": true,
    "longitude": 13.4050,
    "latitude": 52.5200
  },
  {
    "city": "Hamburg",
    "population": 1841000,
    "isCapital": false,
    "longitude": 9.9937,
    "latitude": 53.5511
  }
]

This is a simple JSON array with structured data about cities. Each item in the array is a JSON object with five fields:

• city: the name of the city (text)

• population: the number of inhabitants (number)

• isCapital: whether the city is a capital (true/false)

• longitude and latitude: longitude and latitude of the city in separate properties (number)

What the table would look like after upload

city	population	isCapital	longitude	latitude
Berlin	3,769,000	true	13.4050	52.5200
Hamburg	1,841,000	false	9.9937	53.5511

This is structured data that contains geographic information - but not yet in a format that the Polyteia Platform can recognize as geometry.

To use the data in a map visualization, the coordinates need to be converted into a proper geometry format before upload, such as a point with a type and coordinates field.

What is GeoJSON

GeoJSON is a standardized format for geographic shapes like points, lines, and polygons. It builds on regular JSON but adds specific rules for describing geometry and location.

A valid GeoJSON object has:

• a type (e.g. Point, Polygon)

• a geometry field with shape and coordinates

• optional properties with additional information

Example: Berlin districts (polygons)

[ 
  {
    "type": "FeatureCollection",
    "features": [
      {
        "type": "Feature",
        "geometry": {
          "type": "Polygon",
          "coordinates": [[[13.1, 52.5], [13.2, 52.5], [13.2, 52.6], [13.1, 52.6], [13.1, 52.5]]]
        },
        "properties": {
          "bezirk": "Berlin-Mitte",
          "id": "1101"
        }
      }
    ]
  }
]

This is a GeoJSON file that describes a polygon shape (e.g. a district boundary) with additional information:

• The type: FeatureCollection means it's a list of geographic features

• Each feature has:

  • a geometry with the shape (a polygon made of coordinate pairs)

  • properties like the district name (bezirk) and ID

It's the standard format for creating shapes like cities or districts on a map.

Example file download

Using simple JSON with coordinates

Not all geographic data has to follow the full GeoJSON structure. If you're only working with points—like schools, businesses, or hotels—you can use a simpler JSON format, as long as it includes:

• a type: Point

• a coordinates array

These fields must be nested inside each object and appear in the same field (e.g. coordinates or location) for every dataset entry.

Example

{
  "name": "Bright Nest Hotel",
  "coordinates": {
    "type": "Point",
    "coordinates": [13.4078, 52.5114]
  }
}

This structure works well for point-based datasets, even though it's not full GeoJSON. The Polyteia Platform automatically recognizes the coordinates field and converts it into a geometry column—just like with GeoJSON.

If you need shapes like boundaries or districts, you'll need to switch to full GeoJSON.

Example file download

Upload JSON or GeoJSON file

To create a map visualization, your dataset must contain geographic information—either as polygons (e.g. district boundaries) or points (e.g. location coordinates). This data must be uploaded in one of the following formats:

Format	Description	Supported shapes	Auto-converts to geometry?
.geojson	Standard format for describing map shapes	Polygons, points	Yes
.json	Must follow GeoJSON-like structure (type + coordinates)	Usually points	Yes, if formatted correctly

To upload the data:

• Follow the steps in Create dataset to upload your .geojson or .json file

After upload, the Polyteia Platform will:

• recognize valid GeoJSON and create a geometry column

• attempt to convert point-based JSON fields (e.g. location, coordinates) if the structure contains type and coordinates

If no geometry is detected, the column will be treated as text or nested object. In this case, you need to ensure the format is adjusted in your uploaded file and then try uploading the file again.

Good to know

• When uploading a .geojson file, the Polyteia Platform automatically recognizes the format and converts it into a geometry column

• When uploading a .json file, the Polyteia Platform only treats it as geographic if it contains a type and coordinates field in the correct GeoJSON structure

• If your JSON file uses nested fields (like coordinates), make sure each object is consistently formatted