Importing existing Geojson data

Often you will want to import existing Geojson data into your map. This can be done with the gm.features.importGeoJsonFeature. This method accepts a Geojson object and adds it to the map.

For FeatureCollections, you can use the gm.features.importGeoJson method. This will add all features in the collection to the Geoman instance and to the map.

Example usage

In this case we have hardcoded a Geojson feature in the export const demoFeature: Array<GeoJsonImportFeature> = [ const. This could be fetched from an API or a file or a database.

export const demoFeature: GeoJsonImportFeature =
  {
    type: 'Feature',
    properties: {
      shape: 'polygon',
    },
    geometry: {
      type: 'MultiPolygon',
      coordinates: [
        [
          [
            [
              -8.151855468751137,
              49.446665467090696,
            ],
            // ...
          ]
        ]
      ]
    }
  }
  // ... more features

The gm.features.importGeoJsonFeature method is then called to add the feature to the map:

gm.features.importGeoJsonFeature(demoFeature);

Adding a Geojson FeatureCollection

If your data was formatted as a FeatureCollection, you need either import the entire collection using importGeoJson, or you need to extract the individual features and call importGeoJsonFeature on each feature:

const fc = {
  type: 'FeatureCollection',
  features: [
    {
      type: 'Feature',
      properties: {
        shape: 'polygon',
      },
      geometry: {
        type: 'MultiPolygon',
        coordinates: [
          [
            [
              [
                -8.151855468751137,
                49.446665467090696,
              ],
              // ...
            ]
          ]
        ]
      }
    },
    // ... more features
  ]
}

// Add each feature from the collection individually
fc.features.forEach((feature) => {
  gm.features.importGeoJsonFeature(feature);
});

// Or add the entire collection at once (recommended)
gm.features.importGeoJson(fc);

Using the overwrite option

When importing GeoJSON features that may have IDs matching existing features, you can use the overwrite option to replace them:

// Import with overwrite enabled - existing features with matching IDs will be replaced
const result = await gm.features.importGeoJson(fc, { overwrite: true });

console.log(result.stats.overwritten); // Number of features that were replaced

When overwrite: true is set, existing features with matching IDs are deleted before importing the new features. The stats.overwritten count in the result tracks how many features were replaced.

Using a custom ID property

You can specify which property to use as the feature ID during import:

// Use the 'customId' property from feature.properties as the feature ID
const result = await gm.features.importGeoJson(fc, { idPropertyName: 'customId' });

Handling ID collisions

When overwrite is not set, you can control what happens to an imported feature whose ID collides with one already present using the onIdCollision option:

// 'skip' (default): the colliding feature is not imported (counted as failed)
const skipped = await gm.features.importGeoJson(fc, { onIdCollision: 'skip' });

// 'reassign': the colliding feature is imported with a fresh, unique ID so that
// no feature is ever silently dropped. The assigned ID is reported in addedFeatures.
const reassigned = await gm.features.importGeoJson(fc, { onIdCollision: 'reassign' });

Full Demo example

We have put together a list of examples from the Maplibre-Geoman Examples Repository that showcase how to import Geojson data into the map. All the examples import features from a fixtures file and add them to the map using the gm.features.importGeoJsonFeature method.

See the Examples page for more information.

API Reference

ImportGeoJsonOptions

interface ImportGeoJsonOptions {
  idPropertyName?: string;  // Use a specific property as the feature ID
  overwrite?: boolean;      // When true, replace existing features with matching IDs
  // How to handle a feature whose ID collides with an existing one (when overwrite is not set):
  // - 'skip' (default): the colliding feature is not imported (counted as failed)
  // - 'reassign': the colliding feature is imported with a fresh unique ID
  onIdCollision?: 'skip' | 'reassign';
}

Note: importGeoJson and importGeoJsonFeature are asynchronous and return a Promise. await them (or use .then()) when you need the import result or want to ensure the features are added before continuing.

GeoJsonImportFeature

interface GeoJsonImportFeature {
  type: 'Feature';
  properties: {
    shape: string;
    [key: string]: any;
  };
  geometry: {
    type: string;
    coordinates: any[];
  };
}

Import Result

interface ImportGeoJsonResult {
  stats: {
    total: number;      // Total features processed
    success: number;    // Successfully imported features
    failed: number;     // Features that failed to import
    overwritten: number; // Features replaced (when overwrite: true)
  };
  addedFeatures: Array<FeatureData>; // The imported FeatureData instances
}