Using place sources from the API

Place sources allow you to import a large numbers of places at once using the API. You can upload all your places and then run the import and all the changes will happen in Mapwize's backend. Places will be created, updated or deleted depending on the difference between the new set of places and the previous one.

When using the place source, it is important to note that you should always send the full list of places (of that source) and not just the ones that have changed as we consider that if a place is not in the list anymore it's because it should be deleted.

Places imported through the source will be flagged as such in the Studio. Users should not manually modify the place in the Studio and they will see a warning if they try to.

If you delete the place source, you have the choice to delete all the places that were imported from that source or to keep them. If they are kept, they will be disconnected from the source and look as if they had been manually input.

Templates

You have 2 options when importing places:

• You can send completely formed Mapwize Place objects and they will be imported as is.
• Or you can specify a template and use the properties in your data to create places.

The template is particularly useful when you need to create similar places from a table. Imagine you have imported a map of your event with booth numbers coming from AutoCAD in your technical universe. Now you want to create places in the visitor universe on top of each booth with the name of the exhibitor. You can use a place source with template to import your Excel file matching booth number and exhibitor name.

The "template" property can be set in the source config. It should be a wellformed Mapwize Place object containing Mustache syntax to replace values with the columns of the file.

If you are using "template", you also need to define "config.propertyForGeoreference" in the source that will define which column of your file links to the name of the existing places from which the geometry will be copied, like the booth number in our example.

Importing geometries from the file is not supported when using templates. If you want to import full geometries, you should not use the template option.

Formats

Places can be uploaded and retrieved in JSON, XLSX or CSV format.

If you are sending full place objects and not using template, we strongly advise to use the JSON format to avoid issue in the conversion of deep objects.

Creating a source

To create a source, you'll need to send a POST request. The full documentation can be found here: https://documenter.getpostman.com/view/3032676/RW1aKg3f?version=latest#3fa2a6b1-4df4-4335-8529-cc496ba92092

POST https://api.mapwize.io/v1/venues/{{venueId}}/sources/place?api_key={{api_key}}

with body

{"name":"Source Name"}

Uploading the places

You can upload a JSON, XLSX or CSV file, as a multipart file, using

POST /v1/venues/$venueId/sources/place/$placesourceId/data

 You can also upload the places in JSON format directly as part of the body using the ?raw parameter

POST /v1/venues/$venueId/sources/place/$placesourceId/data?raw=true

Setting the config

If you are using the templating, you need to set the source config using

PUT https://api.mapwize.io/v1/venues/{{venueId}}/sources/place/{{placeSourceId}}/config?api_key={{api_key}}

{
    "propertyForGeoreference": "stand",
    "template": {
        "name": "{{stand}}",
        "placeTypeId": "55e95212db99cc0b00adc56d",
        "order": 0,
        "isVisible": true,
        "isPublished": true,
        "isSearchable": true,
        "isClickable": true,
        "universes": [],
        "style": {
            "markerDisplay": true
        },
        "translations": [
            {
                "title": "{{stand}}",
                "subTitle": "{{info}}",
                "language": "fr"
            }
        ]
    }
}

Importing the places

POST /v1/venues/$venueId/sources/place/$placesourceId/run

You will then be able to retrieve the status of the import and the list of any error that could have happened during the import.

The detailed routes can be found here: https://documenter.getpostman.com/view/3032676/RW1aKg3f?version=latest#3f9d8573-6ffe-4e2a-a826-b81216facd6a