This page is for those who intend to extend the plugin's built-in known set of places, for personal use or to share with the community.

Exception made for aeronautics data information, which is read from the X-Plane's internal navigation database, xPlaces gets all its data from text (JSON) files structured in the proper "xPlaces" format, found in the xPlaces/geodata and xPlaces/geodata/user folders (we'll see more about this split later). These files are called xPlaces Libraries. xPlaces should be seen as an extensible "data loader and drawer" rather than a "data holder".

The plugin already comes with a complete set of libraries, covering all countries worldwide.
So... why extending it ?
Here are some ideas of places that would be fun to bring into the X-Plane scenery:

What follows is a tutorial on how to build a new library.
Being a text file, once it's done, your library will be very easy to share.

The JSON file format

Each library is defined by a single .json file, which is a text file, named with extension .json. Its content must follow the json syntax rules: for more detailed information see here. Anyway, you don't need to be an IT specialist to write one, just follow the following very basic tutorial.

For complex libraries, using a json editor software will make life easier.
A good tool (online) is jsoneditoronline.org

HOW TO BUILD A NEW PLACES LIBRARY

We want to build a very simple library: a library with one single place: the Eiffel Tower!

Create a new text file named MyFirstLibrary.json inside your /Resources/plugins/xPlaces/geodata/user/ folder. Well, you can name that file whatever you like, just be sure to put the .json extension at the end of the filename. In order to be able to manage file extensions, you might need to deactivate the default windows behaviour: hide extensions for known file types, depending on your operating system configurations.

Now let's put some simple content into that file: use a text editor of your choice.

Download

For now don't bother that much about all the syntactical details (brackets, quotes, ...).
Just note this:
   - all the blue elements are property names; all orange elemements are property values
   - author, description and issueDate contains a single value (specified within quotes), while places is a container: it will contain a SET of elements (for now it's empty)

All the elements included in this example are mandatory in any xplaces library, so they must be specified.
They define what one expects: the author, description, issue date of the library, and a set of places.

Now we need to tell the plugin it needs to reload its places database, to get the new library loaded. Do this by toggling the xPlaces console's settings pane and select Reload Places Database. No need to restart anything: just put your libraries into the right folder and reload.

You'll be asked whether to load all the places or the user places only. Choose user places, so the plugin will reload the libraries in /geodata/user/ folder only, being many times faster than reloading its full world coverage! 

Popup the database view pane and see the result: your first library has been loaded successfully! Its author, description and places count seem what expected. Great job!

Ok, now that we learned how to "talk to xPlaces", it's time to include the Eiffel Tower data in our library. Edit the JSON file content as follows:

Download

As you can see, a place is made itself by a set of attributes with respective values. About name, lat and lon there's not that much to say: they are the name of the place and its GPS coordinates. type is the category of the place: 'C' means CUSTOM: that's the right one to use for user libraries. subtype, for custom places, tells xPlaces which color you want the place to be drawn in. At this time only three colors are supported: 'W' = white, 'O' = orange, 'P' = purple.

Let's move on: make sure you saved the updated file and reload the user libraries again.
The database view pane will now confirm that the MyFirstLibrary.json now contains one place.

It's time to see the real effect of your effort: make sure the CUSTOM global switch is turned on in your xplaces console. Move your aircraft to Paris Orly airport (LFPO), takeoff, gain some altitude, fly heading south-west and... take a look outside: the Eiffel Tower is right there!

Let's now add two more famous places to our library: Notre Dame and Palais Garnier.
We want them drawn in orange and purple.
Note that each place must be separated from the next one with a comma:

Download

As usual, save the modified JSON file, go back to xPlaces console and reload the places database ("user places" only). Here's what you'll get:

Errors Management

The content of each places library is validated by the plugin before being loaded and drawn into the scenery. Any validation error is shown in the database view panel. The loading phase of each library is somehow "transactional": either the library is fully loaded, or it's not loaded at all. No partial loading is allowed. Let's "ruin" out brand new library and see what happens... remove the author and issueDate properties, save the file and reload the places database as usual:

Download

Popup the database view panel and that will be the result. Note that no places were loaded.

Now, go back to the working version of the library and this time remove the lat and subtype properties of the Eiffel Tower item:

Download
 

Here's the esit of the reload.