JSON and GeoJSON

Learn about JSON and GeoJSON formats for geographic data.

To use a map chart in the Polyteia Platform, your data must include geographic shapes. These are described using a format called GeoJSON, which is a geographic version of JSON.

This article explains what both formats are and how they work—so you can prepare or upload valid files that the platform can convert and visualize.

Other geographic shape data types like shape files will follow with 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.

Absolutely! Here's the updated example with added longitude and latitude fields, followed by a table showing what the data would look like once uploaded and flattened into a tabular format.

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 containing structured data about cities. Each item in the array is a JSON object with three 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: the city's longitude and latitude 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 includes geographic information - but not in the format the Polyteia Platform can recognize as geometry yet.

To use it in a map chart, 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 extra 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 extra 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 drawing shapes like cities or districts on a map.

Example file download

1MB

bezirksgrenzen.geojson

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, offices, 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. Koordinaten or location) for every row.

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 will automatically detect the "coordinates" field and convert it into a geometry column—just like it would with GeoJSON.

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

Example file download

30KB

berlin_hotels.json

Uploading a JSON or GeoJSON file

To create a map chart, 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 properly

To upload the data:

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

After upload, the platform will:

• automatically detect valid GeoJSON and create a geometry column;

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

If no geometry is detected, the column will be treated as text or a nested object. In this case you need to make sure the format is adjusted in your uploaded file and then try to re-upload the file.

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 Koordinaten), make sure each object is consistently formatted.