# Introduction
## Mapeo is a free, easy-to-use, open source set of tools for collecting and mapping information.
Mapeo was built by [Digital Democracy](https://www.digital-democracy.org) with and for earth defenders to easily document environmental & human rights information and to collect data about their land. It was designed to work in entirely offline environments, is highly customizable, and built on a decentralized peer-to-peer database that allows communities to own their own data.
## About this Guide
This site provides an introduction to the Mapeo tools and a collection of training & technical resources to support Mapeo users.
The site is divided into the following sections:
* **Overview**\
Basic information about the Mapeo tools
* **Quick Start Guide**\
Instructions for installing and testing Mapeo's default functionality
* **Complete Reference Guide**\
A complete collection of resources on planning & implementing projects using Mapeo and customization of the tools
### Use of this guide
Digital Democracy would like both Mapeo and the Mapeo reference materials we develop to help communities find ways to support **autonomy**, **accesibility** and **collaboration** in their projects. We know that people accessing this online resource will have diverse interests, goals, needs, and technical literacy. For this reason, there are a variety of paths to access information and levels of details users may be looking for. All pages in this guide can also be [saved in PDF format and printed for use offline](/complete-reference-guide/troubleshooting/saving-and-printing-mapeo-reference-materials).
*Feel free to make use of these resources under the creative commons license terms:* [Attribution-NonCommercial 4.0 International](https://creativecommons.org/licenses/by-nc/4.0/).
**Translation**\
We strive to make our tools & resources accessible and available to communities in their local languages. If you'd like to contribute to translating this guide, please see the section on [Translating Mapeo](/complete-reference-guide/customization-options/translating) to learn how to get started.
#### Open Source Development
Mapeo and all of Digital Democracy's technical development is open source. Visit the [FOR DEVELOPERS](/for-developers/mapeo-repositories) section for more information.
*Mapeo is a project of Digital Democracy, a non-profit organization that partners with earth defenders to co-develop technology for social justice. For more information on Digital Democracy, and how to support our user-centered co-development process visit* [*our website*](https://www.digital-democracy.org)*.*
# About Mapeo
## Mapeo is a free, easy-to-use set of tools for collecting and mapping information.
Mapeo was co-designed and developed with Indigenous communities who face threats to their land such as illegal gold mining, oil contamination and poaching. It was built to support frontline groups to document these activities in order to take community action against them, report key information to authorities, file lawsuits, launch media campaigns, or create maps for land claims. To learn more about how Mapeo is currently being used, see [How Mapeo is being used](/overview/about-mapeo/how-mapeo-is-being-used).
Mapeo is open source software that benefits from continued feedback from our users across the world.
## Key features of Mapeo
* **Simple to use and learn**\
Even if you have never used a smartphone phone before, you can learn to collect data, GPS points and photos with Mapeo Mobile in a few hours. Mapeo Desktop does require some computer skills, but has a simple interface with a limited number of features. For more complex analysis or mapping work you can export your data to other tools. The simplicity of the tools helps support wide community involvement and ownership of projects.
* **Works in completely offline environments**\
All data collected or created with Mapeo is stored directly on your device in Mapeo's embedded database, without the need for an internet connection or centralized server. Users of Mapeo Mobile and Desktop can synchronize or exchange data over a local Wi-Fi network. The data never leaves your local Wi-Fi network and does not require an internet connection. Mapeo Desktop can also exchange information via a file using a USB drive.
* **Uses a peer-to-peer database**\
All the data you collect using Mapeo is stored locally on your device, not on a server or on the internet. When you synchronize with other Mapeo users in your project, you each get a copy of the data that each person has collected, so every device ends up with a complete copy of all the data in the project.
* **Highly customizable**\
You can customize the language, maps and information you collect. You can add detailed offline maps of your area, and change the icons and questions used for data collection. Mapeo has been translated into a number of languages already and anyone can add more.
* **Secure, unfalsifiable data**\
All data collected with Mapeo has encrypted logs that can be verified for authenticity. Similar to a blockchain, data is secured by cryptographic proofs, so you can verify that no record in the log has been changed or tampered with. Private projects can be created using secure project keys which limit who one can synchronize data with.
# Mapeo tools
Mapeo is a set of digital tools, designed to support collaborative data collection and mapping in offline environments.
There are two highly-customizable Mapeo apps that can be used together or individually, depending on your goals:
* [**Mapeo Mobile**](#mapeo-mobile)
* [**Mapeo Desktop**](#mapeo-desktop)
Mapeo Mobile and Desktop are built on top of [**Mapeo Core**](#mapeo-core), an embedded peer-to-peer database that allows users to own their own data, directly on their devices, without the need for an internet connection or to share information with a centralized server.
## Mapeo Mobile
Mapeo Mobile is a smartphone application (currently for Android only) that allows you to collect and map information. Using your phone's GPS, you can mark points on a map for your current location and add photos, notes and other details about what is happening. Information can be shared with collaborators who are using Mapeo, or with external contacts via email or other messaging apps.
Mapeo Mobile can be translated into local languages, customized to use offline maps, and tailored to collect specific types of information.
## Mapeo Desktop
Mapeo Desktop is a computer application that allows you to aggregate, view and manage data collected with Mapeo Mobile. Data from Mapeo Desktop can be shared with collaborators who are using Mapeo or exported to PDF reports, CSV files, GeoJSON files or published to the web using [Mapeo Webmaps](/complete-reference-guide/mapeo-desktop-use/using-mapeo-desktop-to-manage-mapeo-mobile-data/exporting-and-sharing-externally#export-as-web-map).
Mapeo Desktop also offers a simple interface for adding or creating territory information for making maps. It provides a basic set of mapping features that are more accessible to new tech users than other available geographic information tools, but exporting maps requires knowledge of other software.
Like Mapeo Mobile, Mapeo Desktop can be translated into local languages, customized to use offline maps, and tailored to collect specific types of information.
## Mapeo Core
Mapeo Mobile and Mapeo Desktop are both built on top of Mapeo Core to securely store the geographic data, details and media created by users. Mapeo Core is an offline-first, peer-to-peer embedded database that allows users to own their own data, directly on their devices, without the need for an internet connection or to share information with a centralized server.
Mapeo Core is built upon [**Hypercore**](https://hypercore-protocol.org), which is an append-only log of actions (create, edit, delete data). Data is secured by cryptographic proofs -- every record written has a signature that also references the signature of every previous record/row in the log -- so you can never change or edit anything already written to the log. For more on Mapeo Core and data integrity, see [here](https://wp.digital-democracy.org/cooperative-ownership-of-data-without-blockchain/).
{% hint style="info" %}
To learn more about additional tools and modules that support use of Mapeo, see [Mapeo repositories](/for-developers/mapeo-repositories) in the **FOR DEVELOPERS** section.
{% endhint %}
# Peer-to-peer & Mapeo sync
## Mapeo's peer-to-peer database
Unlike traditional apps where all the data is stored on a central server (in the cloud or in an office), the Mapeo database is integrated into the application on your device, and every device (smartphone or computer) participating in your project can have a copy of all the data. This is called a peer-to-peer database. We made this choice so that Mapeo can work entirely offline and does not require the user to set up any database or machine for storing data.
This peer-to-peer database allows users to transfer data to other users in the field without internet, and several users with computers or smartphones can all work on the same dataset and share edits.
### **Main characteristics:**
* **Data ownership and control**\
Data collected with Mapeo is stored directly on the devices used for data collection and can be shared with other smartphones or computers that participate in the same project. This way, the information does not exist solely on one device. No one else, not even us, has access to this data. Mapeo users are the owners of the information collected and have total control over it. In other words, your data stays in your team, in your community. To learn more about the embedded database Mapeo is built on, see the [Mapeo tools](/overview/about-mapeo/mapeo-tools#mapeo-core) section.
* **Peer-to-peer data sharing**\
All devices connected to a peer-to-peer network can have the same hierarchical position within the network. Information is shared directly between different devices using a synchronization process in which each device receives and shares data. Two Mapeo devices can sync with each other at a time, and devices must be part of the same project (ie. using same [configuration](/complete-reference-guide/will-mapeo-work-out-of-the-box-for-me/default-configuration#about-configurations)) to sync with one another. All devices that synchronize end up having the same information, and changes made on one device will be reflected on the other devices after syncing.
* **Offline synchronization**\
Through synchronization, users can transfer data to a computer or smartphone in the field completely offline, and several users with computers and smartphones can all work on the same dataset and share edits. Offline synchronization between smartphones and computers is currently done via Wi-Fi. You can create a Wi-Fi network in the field using a cheap ($25) mobile router or a third device capable of serving as an offline hotspot. **The Wi-Fi network does not need to have to have an internet connection.** Mapeo computers can also synchronize offline using a generated sync file.\
* **Requires a sync protocol**\
We strongly encourage having a methodical [synchronization protocol](/complete-reference-guide/essentials-for-a-successful-mapeo-project/creating-user-protocols) for devices within your project to guarantee that all data is included in the shared database and no data is lost along the way. For all the information collected in a project to be present on the different devices, it is essential to plan how, when, and where the synchronization process between devices will occur. This is especially important in projects where participants work in distant places and do not coincide with other members of their team on a regular basis.
* **Data back-up**\
By synchronizing systematically and on a regular basis with other devices, you ensure that there is a back-up copy of all data. If a device in your project is lost, you can synchronize a new device with another device in the project to restore the data. **Any data that has not been synchronized with other devices will not have a backup.**\
# How Mapeo is being used
Mapeo is currently being used by a variety of communities around the globe to support territory mapping and monitoring efforts. Below are a few examples. For more detailed case studies, partner stories and information about other tool for mapping and monitoring, check out our [Earth Defenders Toolkit](https://www.earthdefenderstoolkit.com) website.
### **Environmental Monitoring in Peru**
> Indigenous Community monitors working within [ECA Amarakaeri in South East Peru are using Mapeo Mobile and Desktop](https://www.earthdefenderstoolkit.com/community/monitoring-the-amarakaeri-communal-reserve-in-peru/) as part of a co-management program of a Reserved area. Together with park rangers, they collect data on illegal gold mining and other impacts to the Reserve and use these for internal decision making and action as well as sharing with the authorities for any illegalities to be addressed.
### **Territory Mapping in Kenya**
> The [Ogiek Indigenous People of Mount Elgon are using Mapeo Mobile and Desktop to map important sites](https://www.digital-democracy.org/blog/mapping-ogiek-ancestral-lands-in-kenya-using-mapeo-during-a-pandemic/) on their lands as part of a historical land claim.
### **Ancestral Mapping in Ecuador**
> The Siekopai people of Northern Ecuador used Mapeo Desktop in their villages to explore satellite imagery of their ancestral lands with the elders, and document stories associated with lakes and old settlements. [Watch video](https://vimeo.com/175900565).
### **Disaster-Risk Management for Climate-Vulnerable Populations in Thailand**
> Village health volunteers in coastal Thailand are using Mapeo to collect data on vulnerable people, to ensure they can receive immediate and targeted help in case of natural disaster.
# Is Mapeo right for me?
There are many tools and pieces of software that you could use for making maps and collecting data. Mapeo was designed to meet the needs of specific users, who:
* are collecting data in primarily offline environments
* often have limited previous experience with technology
* are working collaboratively on mapping or monitoring projects and using shared data sets
* want ownership over their data and the power to decide if and when data is shared with external actors or centralized servers
* have specific data collection requirements
* want to view and gather information in their native languages
* need a tool that is free to use
Mapeo may not be the right tool for all projects. When evaluating whether Mapeo will be a good choice, we encourage you to try out the tools (see the [Quick Start Guide](/quick-start-guide/getting-started)) and please keep in mind the following:
* **Equipment requirements**\
Mapeo Mobile is currently available for **Android only**. (An iOS version is in development for 2022.) Mapeo Desktop works on Windows, Mac and Linux machines.\
\
Mapeo Mobile uses Wi-Fi networks to synchronize data between devices. To synchronize data with Mapeo Mobile in offline areas, you will need a portable router (this does not require an internet connection) or a third device capable of creating a local network offline or hotspot.
* **Peer-to-peer architecture**\
The Mapeo tools are based on a peer-to-peer database, which means there is no centralized server aggregating information collected by users. Two devices that are participating in the same Mapeo project can synchronize or exchange data at a time.\
\
Synchronized devices have identical copies of the Mapeo database and can serve as backups if a device is lost or damaged. **Please note that data that has not been synchronized will not have a backup.** For more details on peer-to-peer architecture and syncing, see [Peer-to-peer & Mapeo sync](/overview/about-mapeo/peer-to-peer-and-mapeo-sync).\
\
It is important to think through in advance how the participating users or devices in your project will share information, as there are a variety of possible synchronizing patterns. For more on this, see [Creating user protocols](/complete-reference-guide/essentials-for-a-successful-mapeo-project/creating-user-protocols).
* **Customization and required technical skills**\
Mapeo comes with out-of-the box options that can be used right away, without any customization. To learn more about whether these default options will work for your project, see [Will Mapeo work out-of-the-box for me?](/complete-reference-guide/will-mapeo-work-out-of-the-box-for-me)\
\
Mapeo was also built to be highly customizable and allow users to adapt its interface to meet the needs of specific projects. Mapeo is currently available in many languages and can easily be translated into new ones.\
\
Adapting Mapeo to use custom categories, icons, questions and background maps currently requires significant technical knowledge and will not be accessible to all users. If you believe customization will be necessary for your project, please consult the section on [Customization options](/complete-reference-guide/customization-options) to determine whether your team has the required technical skills.
* **Security**\
As an offline-first, peer-to-peer set of tools, Mapeo can offer a path for data collection and exchange with fewer technological vulnerabilities than other available tools.\
\
However, the use of any technology can introduce new security concerns and risks. Before choosing to use Mapeo or other alternatives, we strongly encourage reviewing the section on [Security & risk assessment](/complete-reference-guide/essentials-for-a-successful-mapeo-project/security-and-risk-assessment).
#### Alternative tools
If Mapeo doesn't seem like the right fit for your needs, check out the **Toolfinder** on our [Earth Defenders Toolkit ](https://www.earthdefenderstoolkit.com/toolfinder/)site to learn more about other tools for territory mapping and monitoring.
# FAQs
Frequently asked questions about Mapeo.
{% hint style="info" %}
For help with technical issues using Mapeo, see the [Troubleshooting](/complete-reference-guide/troubleshooting) section.
{% endhint %}
* [Who made Mapeo?](#who-made-mapeo)
* [Is Mapeo free to use?](#is-mapeo-free-to-use)
* [What kind of data can Mapeo collect?](#what-kind-of-data-can-mapeo-collect)
* [What languages is Mapeo available in?](#what-languages-is-mapeo-available-in)
* [Is Mapeo Mobile available for iOS?](#is-mapeo-mobile-available-for-ios)
* [Do I need to customize Mapeo to use it?](#do-i-need-to-customize-mapeo-to-use-it)
* [How does Mapeo work offline?](#how-does-mapeo-work-offline)
* [Does Mapeo use a Blockchain?](#does-mapeo-use-a-blockchain)
* [Who will have access to my data?](#who-will-have-access-to-my-data)
* [Does Mapeo collect information on users?](#does-mapeo-collect-information-on-users)
* [What happens if Mapeo loses financial support? Will my data be inaccessible?](#what-happens-if-mapeo-loses-financial-support-will-my-data-be-inaccessible)
* [Can you help me deploy Mapeo?](#can-you-help-me-deploy-mapeo)
* [How can I report bugs or problems using Mapeo?](#how-can-i-report-bugs-or-problems-using-mapeo)
## Who made Mapeo?
Mapeo was built by [**Digital Democracy**](https://www.digital-democracy.org) in close collaboration with Indigenous partners in the Amazon who are on the front lines of defending their rights and territories.\
\
Digital Democracy is a non-profit organization that works in solidarity with marginalized communities to use technology to defend their rights. For more information on Digital Democracy and our partners, visit [our website](https://www.digital-democracy.org).
## Is Mapeo free to use?
Yes, all Mapeo tools and features are free to install and use.
## What kind of data can Mapeo collect?
With **Mapeo Mobile**, you can collect geographic points to mark your current location, and add associated photos, description, and details. Users assign each point collected to a category. Check out the [Mapeo Mobile Quick Start Guide](/quick-start-guide/mapeo-mobile) to see an overview of mobile data collection.
With **Mapeo Desktop** Territory mode, you can create points, lines and areas (polygons) on a map and add an associated category, description, and details.
For more on Mapeo's default categories and details fields, see [Default configuration](/complete-reference-guide/will-mapeo-work-out-of-the-box-for-me/default-configuration). To learn about customizing these options, see [Custom configurations](/complete-reference-guide/customization-options/custom-configurations).
## What languages is Mapeo available in?
Mapeo is currently available in over 8 languages, including:
* English
* Spanish
* Portuguese
Mapeo can be translated into additional languages on [Crowdin](https://crowdin.com/). For more information, see [Translating Mapeo & default configurations](/complete-reference-guide/customization-options/translating)
## Is Mapeo Mobile available for iOS?
Mapeo Mobile is currently available for Android only. It is on our roadmap to release a version for iOS in the future.
## Do I need to customize Mapeo to use it?
When you install Mapeo, it comes with default options that can be used right away, without any customization. To learn more about whether these options will work for you, see [Will Mapeo work out-of-the-box for me?](/complete-reference-guide/will-mapeo-work-out-of-the-box-for-me)
Some projects may require customization of data fields or background maps in order to best meet the needs of the project or context. Customization currently requires some technical skills. For more on customization options and technical requirements, see [Customization options](/complete-reference-guide/customization-options).
## How does Mapeo work offline?
Mapeo is built on an embedded peer-to-peer database, so all data collected with Mapeo is stored directly on your device, with no need for an internet connection or centralized server. Users of Mapeo Mobile and Mapeo Desktop can synchronize or exchange data over a local Wi-Fi network. The data never leaves your local Wi-Fi network and does not require an internet connection. Mapeo Desktop can also exchange information via a synchronization file using a USB drive.
For more on how Mapeo stores and synchronizes data, see [Peer-to-peer & Mapeo sync](/overview/about-mapeo/peer-to-peer-and-mapeo-sync).
## Does Mapeo use a Blockchain?
Mapeo uses secure peer-to-peer technology with a distributed ledger, which does not include a public blockchain or consensus.
Public blockchains are designed for a scenario where public transactions must be mediated between participants which are all potentially malicious. These “trustless” transactions are the key assumption of a blockchain that distinguishes it from peer-to-peer technology.
Applications like Mapeo assume that data is managed by the community generating it - and **some of that data may never be publicly accessible.** Mapeo's approach, in contrast, creates a closed group, where data creators are also data stewards, managing their own data and controlling who has access. We take security seriously and maintain protections from third-party attacks such as targeted hacks and surveillance by third-parties. For users of Mapeo, privacy is critical for protecting their ancestral knowledge and environmental monitoring information until it’s ready to be shared with trusted partners.
For more information, [read this blog post](https://wp.digital-democracy.org/cooperative-ownership-of-data-without-blockchain/) and [this paper from Article 19](https://www.article19.org/resources/blockchain-technology-alone-cannot-protect-freedom-of-expression) about why blockchain is not a recommended tool for human rights and freedom of expression.
## Who will have access to my data?
Mapeo was designed to be an offline-first set of tools that centers data sovereignty for its users. That means that the data you collect with Mapeo will only exist on the device it is collected or created with until you choose to share it with other Mapeo project participants or external actors. The data you create will never be stored on external servers or shared with app maintainers or other actors, unless you choose to send it or enable and use Web sync options through Mapeo.
## Does Mapeo collect information on users?
Mapeo collects only basic, anonymized statistics for debugging, designing and understanding to what extent the applications are being used.
## What happens if Mapeo loses financial support? **Will my data be inaccessible?**
Mapeo is built with long-term sustainability as a focus. This goes beyond financial sustainability - we ensure that no single entity or technology is responsible for data storage or access.
Mapeo does not lock your data into a particular data format. You can easily move your data around, and it is kept in its original form. Mapeo Desktop can export data to [SMART](http://smartconservationtools.org/download/), Shapefile, CSV, and GeoJSON. You'll never be locked into using Mapeo software. For more on export options, see [Exporting data & sharing externally](/complete-reference-guide/mapeo-desktop-use/using-mapeo-desktop-to-manage-mapeo-mobile-data/exporting-and-sharing-externally).
## Can you help me deploy Mapeo?
There is a community of active users and maintainers of Mapeo that participate in our public chat channel on [Discord](https://discord.gg/KWRFDh3v73) and on our [Earth Defenders Toolkit Forum](https://forum.earthdefenderstoolkit.com/). We encourage you to consult these spaces for additional tips and ideas on how people are using Mapeo.
Digital Democracy's core team is very small and we have limited capacity to provide direct accompaniment for implementing Mapeo outside of our existing partnerships. In some cases we are able to offer support. To read more about the way we work with partners and different levels of support, see [here](https://drive.google.com/file/d/1c9C1-6v1EHKnfrYDsBn3VNu5qS_pUNMC/view?usp=sharing).
## How can I report bugs or problems using Mapeo?
There is community of active users and maintainers of Mapeo that participate in our public chat channel on Discord. To join the conversation or seek help on technical issues, you can [access the channel here](https://discord.gg/KWRFDh3v73).
# Getting started
The **Quick Start Guide** is intended to help you install and test the basic, out-of-the-box functionality of Mapeo in order to evaluate whether it will be a good fit. This section will not touch on all features or customization of the tools.
The [**Complete Reference Guide**](/complete-reference-guide/welcome) below includes critical information about how to design and implement a project using Mapeo as well as detailed guides for setup and customization of the tools. We recommend using it for starting a new initiative or as a training reference.
# Mapeo Mobile
## Install
To install Mapeo Mobile on your Android device,[ download the latest version on Google Play](https://play.google.com/store/apps/details?id=com.mapeo\&hl=en_US). You can also [download the app as an APK ](https://apk.mapeo.app/latest/)and install it manually on your phone. For more on installation, see [Installing Mapeo Mobile](/complete-reference-guide/mapeo-mobile-installation-setup/installing-mapeo-mobile).
## Collect data
You collect data with Mapeo Mobile in the form of *observations*. An observation is based on a geographic location (a point on the map) and can have associated photos, notes and details.
To create a new observation, tap the **Create observation** button, then select a category.
 
Add a description, photos and details, then tap the **Save** button.
## View observations
Each observation will be marked on the map with a dot. Observations can also be viewed in list form by tapping the **Observations list** button.
 
Tap on an observation from the map or list to view its details.
## Edit an observation
With the details of an observation open, tap the **Edit** button to make changes.
## Share data externally
Tap on the **Share observation** button to send the details of a single observation to a contact outside of Mapeo using one of the communications apps installed on your phone (WhatsApp, Signal, Email, etc.).
## Delete an observation
Tap the **Delete** button to delete an observation and its associated media.
{% hint style="warning" %}
Deleting observations cannot be undone, so exercise caution when using delete.
{% endhint %}
## Synchronize data
Mapeo Mobile allows you to synchronize data with other Mapeo users that are participants of the same project. During synchronization, ALL data from one device will be sent to the other device and vice versa. For more on synchronization, see: [Peer-to-peer & Mapeo sync](/overview/about-mapeo/peer-to-peer-and-mapeo-sync).
To synchronize data between 2 Mapeo Mobile devices that are near each other:
1. Connect both devices to the same Wi-Fi network. (You do not need to have an internet connection.)
2. Tap the **Synchronize** button on both devices.
3. On the **Synchronize** screen, identify the device you wish to synchronize with in the list and tap the **Sync** button beside its name.
4. Keep the **Synchronize** screen open on both devices until the synchronization has completed.
{% hint style="info" %}
For detailed instructions on how to use all features of Mapeo Mobile, see below sections in the Complete Reference Guide:
[Mapeo Mobile installation & setup](/complete-reference-guide/mapeo-mobile-installation-setup)
[Mapeo Mobile use](/complete-reference-guide/mapeo-mobile-use)
{% endhint %}
# Mapeo Desktop
## Install
Download Mapeo Desktop from the [Mapeo website](https://www.digital-democracy.org/mapeo/) and double click the file to launch the installer. For more on installation, see [Installing Mapeo Desktop](/complete-reference-guide/mapeo-desktop-installation-setup/installing-mapeo-desktop).
## Mapeo Desktop for managing Mapeo Mobile data (Observations mode)
**Observations** mode in Mapeo Desktop is designed for viewing, managing and exporting data collected with Mapeo Mobile. The steps below will cover the basics for testing **Observations** mode.
{% hint style="info" %}
For more detailed instructions and information on how to use Mapeo Desktop for creating territory data (**Territory** mode), see the Complete Reference Guide section on [Mapeo Desktop use](/complete-reference-guide/mapeo-desktop-use).
{% endhint %}
## Synchronize Mapeo Mobile data
To get started, synchronize collected data from a Mapeo Mobile device. To synchronize via Wi-Fi, as detailed below, the Mapeo Mobile and Mapeo Desktop devices must be near each other.
### Connect to Wi-Fi
Make sure both the **Mapeo Mobile** device and the **Mapeo Desktop** device are connected to the same Wi-Fi network. (An internet connection is not required.)
### Enter Synchronize mode
In **Mapeo Mobile**, tap the **Synchronize** button to enter the **Synchronize** screen.\
\
In **Mapeo Desktop**, click on **Synchronize** in the **Mapeo modes** panel.
### Start synchronization
On the Mapeo Desktop **Synchronize** screen, identify the mobile device you would like to synchronize with and click on the **Synchronize** button below its name.
{% hint style="warning" %}
**IMPORTANT**: Keep the **Synchronize** screen open on BOTH devices until the synchronization is complete. Interrupting the sync process can result in permanently corrupted data.
{% endhint %}
{% hint style="info" %}
In order to synchronize, Mapeo devices must be connected to the **same Wi-Fi network**, and using the **same project configuration**.
For more detailed instructions on synchronizing in Mapeo Desktop, see [Synchronizing data](/complete-reference-guide/mapeo-desktop-use/using-mapeo-desktop-to-manage-mapeo-mobile-data/syncing-data).
{% endhint %}
## View observations
To view synchronized data, click on **Observations** in the **Mapeo modes** panel.
### Map view
By default, observations are displayed as dots on a map. Click on an individual dot to view the details of that observation.
### Media view
To view observations as a gallery of images, click on **Media** in the **Toolbar** above the map. Click on an individual image to view the details of that observation.
### **Report view**
To view observations in the form of a report, click on **Report** in the **Toolbar.**
## **Filter observations**
To look at a subset of your observations in **Map**, **Media** or **Report** view, use the **Filter** panel to select a specific data range, a subset of categories, or specific data values from details fields.
## **Edit observations**
From **Map** or **Media** view, click on a dot or image to view the full details of the corresponding observation. From **Report** view, use the **EDIT** button in the grey toolbar to open the details of the observation shown in the current page of the report.
With the observation details open, click on a field to add or edit information. Click **SAVE** to save changes.
{% hint style="info" %}
In Mapeo Desktop you cannot modify the creation date, category type or geographic location of an observation.
{% endhint %}
## Delete observations
To delete an observation, open the observation details and click on the**More options** menu. Select **Delete observation** and confirm deletion in the pop-up window.
{% hint style="warning" %}
**Deleting observations cannot be undone, so exercise caution when using delete.**
By deleting observations, you will permanently remove them from your device and all devices you synchronize data with in the future. For more on synchronization, see [Peer-to-peer & Mapeo sync](/overview/about-mapeo/peer-to-peer-and-mapeo-sync)
{% endhint %}
## Export data
Data can be exported to multiple formats from **Observations** mode in Mapeo Desktop. Basic export instructions are included below.
* [Save as PDF Report](#save-as-pdf-report)
* [Export to GeoJSON, CSV, or SMART CSV](#export-to-geojson-csv-or-smart-csv)
* [Export as Web Map](/complete-reference-guide/mapeo-desktop-use/using-mapeo-desktop-to-manage-mapeo-mobile-data/exporting-and-sharing-externally#export-as-web-map) (In Complete Reference Guide)
{% hint style="info" %}
For more details on Mapeo export formats and process, see [Exporting data & sharing externally](/complete-reference-guide/mapeo-desktop-use/using-mapeo-desktop-to-manage-mapeo-mobile-data/exporting-and-sharing-externally) in the Complete Reference Guide.
{% endhint %}
### **Save as PDF Report**
To save a PDF report with the observations collected, go to **Report** view. Filter observations if desired using the **Filter** panel. Hide any fields you don't wish to appear by using the **Hide fields** option in the grey panel above the report.\
\
To save, click on **Save PDF.**
### Export to GeoJSON, CSV, or SMART CSV
To export observations to GeoJSON, CSV or SMART CSV format, click on the **Export options** menu at the top right corner of the Mapeo Desktop window.
Select **Export Observations...** then select the desired data format and options in the Export Observations pop-up window. Click **SAVE** to name the export file and choose the location on your computer where it will be saved.
{% hint style="info" %}
For detailed instructions on all features and uses of Mapeo Desktop, see [Mapeo Desktop use](/complete-reference-guide/mapeo-desktop-use) in the Complete Reference Guide.
{% endhint %}
# Welcome – Introduction
Welcome land defenders, community mappers, resource and impact monitors, data collectors, students, scientists - whoever you are, we hope you have enjoyed playing around with Mapeo using the Quickstart guide above.
If you think that Mapeo might be the right tool for your project, this **Complete** **Reference Guide** is designed to provide you with learning and training materials, suggested workflows, and some examples of real projects in order to help get you set up and using Mapeo in the best possible way for your needs.
There is a LOT of information in the sections below, and there are many different ways of using Mapeo. We don't expect users to make use of every Mapeo feature nor need to read every section, but we do hope that what we are providing here can help users be well informed about technical details that will impact your projects.
# Essentials for a successful Mapeo project
In the pages below you'll find a collection of resources to support in getting a Mapeo project started.
* [Planning a Mapeo project](/complete-reference-guide/essentials-for-a-successful-mapeo-project/planning)
* [Security & risk assessment](/complete-reference-guide/essentials-for-a-successful-mapeo-project/security-and-risk-assessment) (Coming soon)
* [Creating user protocols](/complete-reference-guide/essentials-for-a-successful-mapeo-project/creating-user-protocols) (Coming soon)
Additional information on running trainings in Mapeo can be found in [Mapeo trainings](/complete-reference-guide/training-and-information-sessions).
# Planning a Mapeo project
You may be keen to jump in and get started with data collection, however spending a bit of time upfront thinking through how the project will run, the methodology, team set-up, logistics of gathering data, and how the data collected or created with Mapeo will be used can save you a lot of time and avoid problems and issues later on.
This guide does not aim to give you a blueprint of how to run your project. There are so many different uses of Mapeo, some of these we (Digital Democracy) can imagine, some of them we can't, and each one has its own particular needs, priorities and local contexts. What works in one place might need to be set up very differently for another place, even if the desired outcome is very similar. And likewise what works somewhere at one time, might have to be adjusted for another time as local situations, politics, etc. change.
Hopefully spending time thinking through the questions below will enable you to create a process tailored to your needs and project, and give it the best possible chance of success.
**We are going to run through the following questions:**
* [**Why collect information?**](/complete-reference-guide/essentials-for-a-successful-mapeo-project/planning/why-what-is-the-project-goal) What is the aim of your mapping, monitoring or data collection, what is your goal or desired end product or result?
* [**What outputs do you want?**](/complete-reference-guide/essentials-for-a-successful-mapeo-project/planning/what-outputs-do-you-want) If you already know that you want to build an interactive story map, or produce a quantitative report or file a legal case, this can help shape your project design.
* [**What information do you need to collect in order to meet this aim?**](/complete-reference-guide/essentials-for-a-successful-mapeo-project/planning/what-information-to-collect)
* [**Who should be involved?**](/complete-reference-guide/essentials-for-a-successful-mapeo-project/planning/what-are-your-parameters) What project structure will best meet your aims, who should be involved, what roles do you need, who is making decisions and who are you accountable to?
* [**What are the parameters or limiting factors you are working with?**](/complete-reference-guide/essentials-for-a-successful-mapeo-project/planning/who-is-involved) This refers to your geographical context, infrastructure, accessibility to areas, budgets and equipment availability, time constraints, security risks, etc.
* [**Is Mapeo the right tool for you?** ](/overview/is-mapeo-right-for-me)We think Mapeo is great :) but we know that it has limits and it isn't the right tool for every job. We want to make sure that if you choose Mapeo you understand what it excels at doing and also its weaknesses, to make sure you are set up in the best possible way for success in your project.
### Provisos
Mapeo was co-developed with community land defenders in the Amazon. We have tested, piloted and received feedback on it from people around the world using it for a variety of purposes, and we hope it can serve a wide range of needs. However it is built with the needs of land and rights defenders at its heart, and therefore this guide, and many of the materials produced for Mapeo are also built with these needs at the forefront.
In part because of its design process, and the partners with whom Digital Democracy has worked, we often refer to **community** and **collaborative** processes. Mapeo can definitely also be used by individuals, and a variety of different teams, but many of our partners are using it in local, frontline community contexts, and so the language of this guide centers them. We also understand that communities are not homogenous and mean different things in different places, and hope that you can read between the lines where necessary to extract the useful parts of this guide for whatever it means to you.
This guide draws on work from our team over the last two decades in indigenous and community land rights and defense. However indigenous and marginalized communities have been defending their land for centuries. There are many projects and initiatives from which the development of Mapeo and the methodologies suggested here have been guided, received inspiration and learned. This reference guide does not aim to provide an exhaustive list of such projects, but at the end of the guide there is a Reference Section which highlights some materials from other sources and initiatives which may be of help to you in planning your project.
All the examples included in the guide are just that, examples. We hope they are helpful and provide some context and illustration to the processes described, but are not intended to be taken and copied as 'out of the box' methodologies. As we hope this planning section will describe, context is everything, and methodology should be carefully considered and adapted to best fit the needs of the project and particular community context.
# What is the project goal?
Why collect information? What is the aim of your mapping, monitoring or data collection, what is your goal or desired end product or result?
So you want to start collecting information, perhaps you are going to be making a map, or perhaps you want to collect evidence of impacts on your land or gather other data or information. The first question to clearly ask of yourself or your community is **WHY? What is it that you hope to gain or change or learn through the project?**
The more detailed an answer you can give to this question the better set up you can get; making sure anyone involved in the project is working towards the same goal and being able to determine the best methodology for meeting it.
For example, if you want to make a map – what is your map for, what impact do you want it to have for you, your team, in the world, etc. Perhaps the map is the end product, or perhaps just one step in a longer process, or maybe the main aim is building relationships, and the map is the means to bring people a focus for working together.
**What if you don't know yet?** Perhaps you know you want to gather data about something that interests you but are not yet sure how you are going to use it. Don't worry, you can refine your aim and build on your project as you go along and learn more.
And remember - all plans change and it is impossible to predict everything in advance. There will be unforeseen outcomes, some beneficial, some possibly challenging, of your project. However having your main goal in mind as you begin to plan your methodology and define what information you are going to collect sets you up to meet any challenges, and welcome any positive changes, in the best way.
# What outputs do you want?
It might be too early to start thinking about outputs, but if you already have a sense of what these might be then they might give some useful direction to your planning process. By output we don't mean the goal or results of your project, although these might overlap, we are referring particularly to concrete materials that result from your Mapeo project.
For example these could be:
* **Printed map / maps:** These might be for an external audience such as the government or a legal body, or they might be for the community itself to use for other purposes. If you are planning on creating a map then consider what information you can show on the map - perhaps you spend a long time collecting stores which then are hard to find space for, or you collect so much information that the map is hard to read.
* **Data reports:** You might want to produce regular reports on the data you collect, or wait until the end of your project and then produce a report with all the data or the highlights. Do your reports include quantitative data that you want to analyse and present in a particular way or is it mainly qualitative data that will need editing or compiling before presentation. Thinking about these can help you to organise your teams and data collection so that you have the data when you need it, in the right format.
* **Alerts:** If you are collecting evidence of something that needs fast action then having an alert system built into your methodology could help. Mapeo Mobile can export datapoints to WhatsApp and other apps so you could potentially send alerts of illegalities straight to law enforcers for immediate action.
* **Interactive webmap:** This could be a good output if you are hoping to build a campaign and want to share some of the project with the public or media - or even for your own community such as for an educational or storytelling resource. It also enables different kinds of information to be present than on a printed map as you can include videos and audio more easily. However it may involve a level of technical expertise or budget beyond the scope of your project, and it is definitely not the right output for every goal.
***
# What information to collect?
When you have clarified the main goal for the project, the next step is to think through carefully what data you want to collect or create. This will not just be dependent upon the final goal, but also on other factors such as the time and funding available, the security situation, and any legal guidelines. So it may be a good idea to read this section again after reading the "What are your parameters" section.
Depending on your needs and capacity you may find that the default configuration and categories that come with Mapeo do the job well enough, or you might want to set up a custom configuration with your own icons and questions tailored to your specific needs. For more on how to do this, see [Creating custom configurations](/complete-reference-guide/customization-options/custom-configurations/creating-custom-configurations)**.** Perhaps, if your project is new and you are still figuring out what is needed, you may want to start collecting data using the default configurations, and learn from that process about what categories and questions you really need.
The simple answer to the question of what information to collect is probably quite obvious from your goal, but when you dig down the answer isn't always that easy. So if you need a territory map for a land claim then you probably need to collect information about territory use, as well as the territory boundaries or limits - but exactly what information do you need, what format should it be in, how much detail do you need, etc. And if you want to collect evidence of illegal gold mining, then you may want to collect georeferenced photos and answer a series of questions about the scale and nature of any impacts found, but what is the best way of framing questions to get you the answers your community and perhaps legal team need to evaluate what is going on and how to take action, and what should you be taking photos of exactly?
Collecting data can be a time-consuming and expensive process, and can raise expectations about outcomes. So thinking this through carefully in advance will help ensure you are a) not wasting your own or others time and resources collecting information that isn't going to be useful and b) not in the situation where you realize at the end of a month-long trip that you need to go back to all the places again because you forgot to collect a crucial bit of data.
Think about the following questions to further clarify exactly what data you should be gathering and how to set up any custom configurations:
* **First think about your goal** and what you know of your needs. Brainstorm with any other team members or with the community about all the possible things you could collect information about, categories and questions, and then start organizing and refining.
* **If possible do some research by talking to allies**, or looking online to see how other similar projects were set up and what data they collected.
* **Are there any rules, restrictions or guidelines** that might determine the kind of information you collect and how to ensure it is usable. For example some governments/authorities might require data to be collected in a particular GPS format, or follow a particular information template, in order to be accepted or easily acted upon.
* **Might the data need to be used in a legal process**, if so there may be specific ways of collecting it, or additional questions you ask, which will enable it to be used more effectively. If possible get local legal advice about this, as it will differ depending on the type of data and the country you are in.
* **Knowing how much information is too much**. Once you start making a map or collecting information it quite fun... maybe a little too fun 🙂. If you have all the time in the world then this may not be a problem, but if people or lands are being threatened you may need to make compromises in terms limiting the data you collect to that which is urgently needed.
# Data types within Mapeo
There are two types of data that Mapeo stores in its database located on devices.
**Mapping data** is meant for generating data for map making or baseline territory information. Mapeo Mapping data can only be viewed, edited and exported with Mapeo Desktop in Territory view. Data collected using Mapeo mobile of GPS devices can be used as precise references for creating new mapping objects. Mapeo mapping data It stores the following information
* **Geometry:** Determines if the map object is a point, a line, or an area.
* **Coordinates:** (specific formate?)
* **Category:** A user selects from a list of categories each with a predefined name, icon, predefined tags and details fields
* **Icons:** Visible in Mapeo Desktop Territory when creating and viewing Mapping data.
* **Tags**: These are additional values to the predefined tags packaged in each category
* **Details** (optional): User filled fields that relate specifically to a category that may help with consistant quality of information
* **Date time of last edit:** This information is appended to each object as a log of changes that get's saved a the end of a mapping editing session for decentralized data consolidation.
**Observation Data** is meant to capture time based information at a specific coordinate with options to add photos and details captured in the field. Observations can only be created using Mapeo Mobile. Observation data can only be viewed, and edited in both Mapeo Mobile and Mapeo Desktop Observations, and each tool offers unique share and export options to output observation data. Mapeo Observation data stores the following information:
* **Geometry:** Observations are always captured as points, to replicate objective human observation when visiting a point of interest.
* **Coordinates:** Available in various formats for data collection. on Mapeo Mobile coordinates are captures automatically using the devices location detection hardware. Mapeo Mobile features include capturing the most precise GPS reading possible when device location is turned on. There is also a manual coordinate entry option is GPS precicion is low or unavailable. Coordinates cannot be edited after capture.
* **GPS metadata**: For forensic varilfication, GPS metadata including altutudem velocity and precision is in each observation captured with the devices GPS features. This information is currently not visible in the user interface.
* **Category:** A user selects from a list of categories each with a predefined name, icon, tags and details fields. These elements are packaged in each category and bases on common user needs. These can be customized \[link]
* **Icons:** Visible in Mapeo Mobile when creating observations and on observation viewing screens. Visible on Mapeo Desktop Observations in Report view
* **Tags**: These are predefined tags packaged in each category. This information is currently not visible in the user interface.
* **Details** (optional): User filled fields that relate specifically to a category that may help with consistant quality of information. In customized configurations add any number of questionscan be added for field surveys to collect quantitative information or evidence. Your questions can be text fields for open descriptions; select one or select multiple from a predefined list of options.
* **Date time of creation:** This information is fundamental to an observation and differenciates it from mapping data as time based data. In both Mapeo Mobile and Mapeo desktop observation data will displayed by Date/time of creation with newest first.
* **Date time of last edit:** This information is appended to each observation as a log of changes for decentralized data consolidation.
* **Photos**: (optional) Stil images can be captured by the Mapeo Mobile camera which automatically links the media files to the observation. \[is any GPS or camera metadata attached to photos?]
# Who should be involved and how?
What team structure will best meet your aims; who should be involved, what roles do you need; who is making decisions and who are you accountable to?
The answer to this question of who should be involved could vary wildly. Perhaps it is just you and your mobile phone, or perhaps it is going to involve thousands of people across multiple countries working together to compile a mass of data. Most of the partners we have worked with directly are somewhere in between, often a community or group of communities with a dedicated team of collaborating to collect data.
However even the projects we have partnered on directly, which might look superficially very similar, have set up their project structures in very different ways, sometimes out of need and sometimes out of preference. So here are some things to consider.
**Are there any traditional or other authorities that should be consulted before you start, or who should be involved in some role?** This is particularly relevant if you are collecting data from indigenous lands (your own or belonging to others) and/or might be collecting potentially sensitive data.
**Who is your project accountable to and how can you ensure you meet their needs?** The answer to this might be the traditional authorities mentioned above, or it could be particular sectors of your community, funders, the future generations or others. Consider how to keep them up to date with project progress if relevant and how to produce materials they will find accessible and useful.
**Do different members of your community hold different knowledge that you want to ensure is represented. How can you honour and involve these people and their knowledge?** Think here about women, elders and young people in particular, and how to ensure they are involved in the work and that they are not simply used to extract information from. Then depending upon the details of your project other groups might arise: traditional healers; skilled artisans; storytellers; health workers etc.
**Consider the ownership of the project:** If the project is meeting needs identified by your community, or collecting data intrinsic to them or their future consider how to ensure the community feels involved in the work and feels ownership over any results. Mapeo was built to try and facilitate community ownership of both projects and data by having a simple interface that could be explained to people without data collection training and people who might be non-literate or unused to computers or smartphones. Involving people at different stages of the project, including the planning phase can help increase this feeling of ownership, as can keeping the data locally, providing frequent feedback and reports back on what is happening, and creating outputs that people can use themselves or see at work.
**What other stakeholders or people with interest or authority do you want to involve?** Perhaps there are people who it would be useful to involve because they could help the project reach its goal such as local authorities, law enforcement, press, park rangers. Think about what role they might have in the project, whether they are consulted about things in advance or are simply informed and kept up to date with project progress. Consider too if there are people you want to keep the work and data secret from due to security or other considerations.
**Who is going to collect your data?** Unless yours is a solo project you are going to need to work with a team or teams of people to collect your data. This will be particularly necessary if you need to cover a large area of land, have time constraints or need different skills on your team. Think about the composition of the team and how you are going to build it - is it something people will volunteer for or will they be asked? Do you need to ensure diverse representation and if so how will you do this? Do you want to involve as many people as possible or have a small team that moves around?
**What other roles do you need?** If you are working with a team or teams of data collectors or mappers you are likely to need someone to coordinate them, help plan trips, collate the data they collect, analyse it and prepare any reports or outputs. This might be the role of a single coordinator, or you might need multiple ones due to the number of people involved or because of cultural or political sensitivities or the way the project ownership is set up. You might also have people involved in training, decision making, liaising with external bodies, helping with legal and communications work etc.
**What skills do people need?** We hope Mapeo is to learn and use, but if you are working in a team and want to collect comparable data people will need some training in how to use the app, and how to use it in the way your project needs. There might be other trainings necessary such as training in basic smartphone usage if people aren't accustomed to it; training in taking good photographs that illustrate what you want to show; training in gps; drones; video; audio recording; oral history recording; GIS software etc. conflict resolution, de-escalation etc depending on the details of your project.
**Create a project protocol:** Writing a protocol, if possible in a collaborative manner, which lays out any different roles within the project, their relationship to the data, agreements about use and ownership of data, any payments that are being made, what will happen to equipment and data at the end of a project etc. can be a way to keep things transparent and accountable and help avoid issues during and after the work.
# What are the parameters?
What are the parameters or limiting factors which you are working with? This refers to your geographic context, infrastructure, accessibility to areas, budgets and equipment availability, time const
No two Mapeo projects will look the same even if they have the same aims and are using the same configuration. There are so many factors which will influence how a project is run including timeline; budget; technology; landscape; seasons; climate; culture; social and political context; etc.
Whilst we can provide some ideas here, any project should be tailored to your particular context taking into account answers to the following questions. Thinking through these questions in advance will also be useful if you ask for help to put together a mapping project from an ally or other organisation.
#### **What is your timeline?**
Is there a particular urgency for the work, a date you need to produce a map or collect data by? If there isn't an internal deadline, are there significant dates external to the project that you might want to work towards or include within your calendar (eg. visits by authorities to the area, International meetings such as COP or UN Working Groups, World Social Forums etc.).
#### **What does the geographical landscape look like? What accessibility issues are there?**
Think about what the land looks like and how you plan to travel around. Some projects might be focused on a small area in town, where people can just travel around on foot on paved roads, other projects might cover tens of thousands of hectares and require travel by river, up steep hills, into swamps etc. Perhaps there are areas you want to access that are off limits (eg. National borders or Industrial installations can have no-go zones around them, or have rules about using GPS or drones etc) Drawing a quick sketchmap of the the area you plan to work within, and marking any significant landmarks, access routes, barriers etc. can help you plan out how you or your team is going to get around and how long this will take, and help identify any challenges you might encounter ahead of time.
#### **Do the seasons affect your work?**
If you plan to collect data at a particular time of year consider how the season or climate might affect this. For example the dry / rainy seasons might impact how easily you can move around the land, and might also impact the type of data you can collect (for example travel by river might be easier in the rainy season, but travel by road or foot might be harder); likewise some operations or activities you want to map or monitor might only occur at certain times of year (eg. illegal logging is linked to seasons, as are fruiting trees and fish/animal movements).
#### **Do you have a budget?**
Do you have or need a budget, and if so how much? Do you intend to pay people to take part or is it volunteer-led? If you don't already have a budget are there parts of the work that are going to need funds such as for purchasing equipment, travelling around or for any meetings you intend to hold.
#### **Do you have or need equipment for your project?**
Mapeo Mobile works on Android phones & tablets and Mapeo Desktop on Windows/Mac/Linux operating systems. Whilst essentially you might just need one smart phone for your project (which you might already have in your back pocket!), depending upon your plan, and particularly if you are going to work with teams in complicated environments you might need to think about other equipment such as spare battery packs if you are doing multi-day trips in remote areas; usb or hard drives for backups; trekking and medical kits for teams; waterproofing for tech that might be exposed to the elements etc., large sheets of paper, marker pens and notebooks for community workshops.
See equipment list for a list of things partners we have worked with have found useful.
#### What is the security situation?
Unfortunately, many frontline defenders are targeted for their work, often risking their lives to defend their peoples rights, lands and futures. Please consider your own safety and that of anyone else involved in the project and take what measures you can to identify risks ahead of time and mitigate them where possible, whilst doing the work that you need to do.
For example:
* Do you need to keep team members, or the names of people interviewed or otherwise involved in the project, or would it be better to involve the media and ensure there is a spotlight on the work?
* Are there places you can avoid going to and questions can avoid asking so as to not trigger dangerous responses?
* Do your teams need some kind of backup to keep them safe, a satellite phone, tracker or civil society accompaniment?
**Data security**
Sometimes it is not people that are at risk but data - consider therefore if you are collecting data that could be valuable to others and how you can best keep it safe.
Information can be sensitive in other ways too: perhaps only certain members of a community normally have access to it (but still want it documented) or perhaps it is information that the community does not want to make public.
Mapeo does not make any of your data public unless you choose to share it, you can create reports or export data which is filtered to exclude sensitive places or pieces of information, and you can share information with team members without it going online.
However there are other measures you can take to protect your information if needed, creating passwords for your devices ... what else?
# Security & risk assessment
{% hint style="info" %}
Coming soon
{% endhint %}
# Creating user protocols
{% hint style="info" %}
Coming soon
{% endhint %}
# Will Mapeo work out-of-the-box for me?
When you install Mapeo, it comes with default options that can be used right away, without any customization. In the following pages, this section details what is automatically included with Mapeo so you can determine whether the app will meet your needs out-of-the-box.
* [Default configuration](/complete-reference-guide/will-mapeo-work-out-of-the-box-for-me/default-configuration)
* [Default background map](/complete-reference-guide/will-mapeo-work-out-of-the-box-for-me/default-base-map)
Mapeo offers many options for customizing categories, icons, questions and background maps but the current customization process requires significant technical knowledge and will not be accessible to all users.
{% hint style="info" %}
For more on customization, see the following section on [Customization options](/complete-reference-guide/customization-options).
{% endhint %}
# Default configuration
### **About configurations**
Mapeo uses *configurations* to determine which categories, icons and questions users see when they are collecting data. For each data point collected with Mapeo, users select a category to classify the point, and may answer questions or respond to prompts to provide more detail about what is being documented.
### Mapeo's default configuration
When you install Mapeo, it comes with a default configuration that includes general categories and questions for territory mapping and monitoring.
#### Categories
The default configuration includes the following data collection categories:
Observations that do not fit these categories can always be collected using the **New point** category.
**Questions**
For every data point collected, users can enter a description of what they are documenting. Default categories also include some additional optional questions or fields that users may fill out when collecting data. For example, the category **Fishing Site** includes the field: ***Name** (Common name of this place*).\
\
 
To review all fields included in the default configuration, install Mapeo and explore the **Add Details** section for each category.
### Beyond the default configuration
Mapeo offers the option to create custom configurations to fit the needs of specific projects. For more information on customization, see [Custom configurations](/complete-reference-guide/customization-options/custom-configurations).
# Default background map
### About background maps
Mapeo uses background maps to show users their current location in the mobile app and as a background for displaying data collected or created with Mapeo.
### Mapeo's default background map
By default, when the device has access to the internet, Mapeo Mobile and Mapeo Desktop in **Observations** mode use a detailed background map that includes geographic elements such as rivers and mountains, as well as some political and urban elements such as borders, cities, roads, and others.
If the device is not connected to the internet, the background map shown by default is much less detailed. In Mapeo Mobile, the offline background map shows country borders and the main water bodies. In Mapeo Desktop, there is currently no default offline background map.
**Online background** **map example**:
\
**Offline background map example**:
### Beyond the default background map
Mapeo offers the option to add a custom background map for use both offline and online. For more on creating and adding custom background maps, see [Custom background maps](/complete-reference-guide/customization-options/custom-base-maps).
# Customization options
Mapeo was built to be highly customizable and allow users to adapt its interface to meet the needs of specific projects. This section covers both translation of the application and the development of custom configurations and base maps in the pages below:
* [Translating Mapeo & default configurations](/complete-reference-guide/customization-options/translating) (novice, intermediate)
* [Custom configurations](/complete-reference-guide/customization-options/custom-configurations)(advanced)
* [Custom background maps](/complete-reference-guide/customization-options/custom-base-maps) (advanced)
{% hint style="warning" %}
Please note that the customization process for configurations and base maps currently requires significant technical knowledge and will not be accessible to all users.
{% endhint %}
# Translating Mapeo & default configurations
Mapeo aims to be accessible to a wide range of communities in their native languages, and to facilitate the process of translating the app and the [default configuration](/complete-reference-guide/will-mapeo-work-out-of-the-box-for-me/default-configuration) into new languages as needed.
While [developing custom configurations](/complete-reference-guide/customization-options/custom-configurations) currently requires significant technical knowledge, the process of translating Mapeo and the default configuration into a new local language can be an easier way to customize the tool for use in your project.
### Translation using Crowdin
Translations for Mapeo are handled through the [Crowdin](https://crowdin.com) platform. It is free to create an account on Crowdin and anyone can contribute translations to Mapeo for new or existing languages.
To begin translating, visit the project page for the area you would like to translate.
* [Mapeo Mobile](https://crowdin.com/project/mapeo-mobile)\
Text and titles for screens and buttons in the mobile app
* [Mapeo Desktop](https://crowdin.com/project/mapeo-desktop)\
Text and titles for screens and buttons in the dekstop app
* [Mapeo's default configuration](https://crowdin.com/project/mapeo-defaut-config)\
Names of data collection categories, and details fields
#### Viewing available languages
On the project home page you can view all languages currently available for the project and how complete translations are.
#### Adding a new language
If the language you wish to translate is not available on the project home page, contact the Project Owner (listed on the bottom right of the page) to request an addition to the list.
#### Contributing translations
To start translating, create an account with Crowdin, visit the relevant project home page, and select the target language. Click on **Translate All** to bring up all relevant text strings.
# Custom configurations
### About custom configurations
Custom configurations are a powerful tool for customization in Mapeo, allowing users to define specific categories, icons, and questionnaires for their projects. Custom category and questionnaire text can be written in any language that can be typed, ensuring that key parts of the Mapeo data collection interface can appear in the native language of the groups using it.
In the current version of Mapeo, configurations also contain a *project key* that allows participants of the same Mapeo project to synchronize data with each other and prevents synchronization with other devices.
### Creating custom configurations
If you have determined that Mapeo's [Default configuration](/complete-reference-guide/will-mapeo-work-out-of-the-box-for-me/default-configuration) will not suit the needs of your project, you have the option of authoring a custom configuration.
{% hint style="warning" %}
Creating custom configurations currently requires significant technical knowledge and will not be accessible to all users.
{% endhint %}
The customization process, detailed in [Creating custom configurations](/complete-reference-guide/customization-options/custom-configurations/creating-custom-configurations), requires comfort editing `JSON` files, generating `SVG` image files, and using GitHub Actions or installing and using `node` packages via the command line.
# Creating custom configurations
{% hint style="warning" %}
Please note that creating custom configurations currently requires significant technical knowledge and will not be accessible to all users.
{% endhint %}
### Overview of the process
There are several steps to creating a custom configuration that will require different skills and the involvement of different actors within a project. You should leave plenty of time prior to the intended start of data collection to allow for community consultation, testing, and iterations of your configuration.
While data structures in Mapeo can be modified during the course of a project, many changes over time can result in messy data outputs. It is worthwhile to test and refine your configuration to the extent possible before putting it into use for data collection.
Once you have completed this process, you will have a Mapeo configuration file (`.mapeosettings`) that can be imported and used in Mapeo Mobile and Destop.
The pages that follow will walk you through the key steps for authoring a custom configuration:
* [Planning configuration & data structure](/complete-reference-guide/customization-options/custom-configurations/creating-custom-configurations/planning-configuration-and-data-structure)\
This section will outline the key customizable elements in a configuration and some considerations when mapping out each area.\
\***No technical knowledge is required.**
* [Coding configuration](/complete-reference-guide/customization-options/custom-configurations/creating-custom-configurations/coding-configuration)\
This section will guide you through translating the planned data structure into the required format and compiling the Mapeo configuration file. \
\***Editing `JSON` files, generating `.svg` files and working with command line or GitHub is required.**
{% hint style="info" %}
For instructions on how to import a configuration file (`.mapeosettings`) into Mapeo, see:
[Importing configurations into Mapeo Mobile](/complete-reference-guide/mapeo-mobile-installation-setup/importing-configurations)
[Importing configurations to Mapeo Desktop](/complete-reference-guide/mapeo-desktop-installation-setup/importing-configurations)
{% endhint %}
# Planning configuration & data structure
Though some key steps of coding configurations require technical skills, initial planning and consultation with project participants is essential to designing effective data structures and does not require coding skills.
To start the customization process, project participants should reflect on the project goals, what kind of data will be needed, and what properties might be required for data outputs.
If you have not already done so, work through the [What information to collect?](/complete-reference-guide/essentials-for-a-successful-mapeo-project/planning/what-information-to-collect) section of this guide as a first step.
### **Data structure**
When planning your configuration, you will need to think through what to include for each of the key customizable areas of Mapeo. The pages that follow will walk you through some considerations when determining content for each area:
* [Categories](/complete-reference-guide/customization-options/custom-configurations/creating-custom-configurations/planning-configuration-and-data-structure/categories)\
When collecting or creating data with Mapeo, users assign a top-level category to each observation or element on the map.
* [Icons](/complete-reference-guide/customization-options/custom-configurations/creating-custom-configurations/planning-configuration-and-data-structure/icons)\
Each category you include must have an icon, or a small graphic to display to users when selecting a category.
* [Details fields](/complete-reference-guide/customization-options/custom-configurations/creating-custom-configurations/planning-configuration-and-data-structure/details-fields) (optional)\
For each category in your configuration, you can include one or more structured data fields (like a mini form or questionnaire) that users can optionally fill out when creating a new observation or map element with that category.
{% hint style="info" %}
Configurations can and often will evolve over time. As you begin collecting data, you will likely find categories, details fields and options you would like to add or modify. Unlike some other survey or data collection tools, Mapeo allows a lot of flexibility for changing configurations over time and does not require that the database be wiped when changes are made.
{% endhint %}
#### **Documenting data structure**
In order to create a Mapeo configuration file, the information you map out for the above areas will need to be translated into `JSON` files and `.svg` image files and then compiled. The details of this process will be covered in [Coding configuration](/complete-reference-guide/customization-options/custom-configurations/creating-custom-configurations/coding-configuration).
If you do not have the technical skills required to code the configuration yourself, the information you define in the following pages for for [Categories](/complete-reference-guide/customization-options/custom-configurations/creating-custom-configurations/planning-configuration-and-data-structure/categories), [Icons](/complete-reference-guide/customization-options/custom-configurations/creating-custom-configurations/planning-configuration-and-data-structure/icons) and [Details fields](/complete-reference-guide/customization-options/custom-configurations/creating-custom-configurations/planning-configuration-and-data-structure/details-fields) can be documented and passed off to a developer or individual with technical skills to code and compile the configuration file.
# Categories
## What are categories?
When collecting or creating data with Mapeo, each observation or element on the map is assigned a category. Users must select a single category when creating a new observation or map element. Categories can be broad or specific, depending on your context and project needs.
### How categories are viewed in Mapeo
**Categories** list in Mapeo Mobile (using the default configuration):\
\
Categories list in the **Filters** panel of Mapeo Desktop (using the default configuration):
## Considerations when defining categories
For each category you choose to include in your configuration, you'll need to determine the following:
* **Name**\
The label users will see in Mapeo when viewing or selecting the category
* **Geometry** \
Each element on the map will be marked as a\
`point`, `line` (eg. a path), or `area` (eg. a zone or lake). You will need to determine which of these geometries users will be able to use for each category.
* All data collected with Mapeo Mobile will be points. If you are using Mapeo Mobile, you should include `point` as a geometry for every category.
* If you are using [Mapeo Desktop **Territory** mode](/complete-reference-guide/mapeo-desktop-use/using-mapeo-desktop-to-create-territory-information) as part of your project, you can also include `line` or `area` for categories where relevant.
* **Color** (optional)\
You have the option of setting a custom color for the map dots or markers for each category in Mapeo Mobile and Mapeo Desktop **Observations** mode.
* **Sort order** (optional)\
You have the option of determining the order in which you would like categories to appear on the Mapeo Mobile **Categories** screen (pictured above). If no order is added, categories will appear alphabetically by name.
### **When defining categories, keep in mind the following:**
* Categories are one of the key ways data can be filtered in Mapeo. Thinking through how you will view and use data once it has been created offers useful perspective when defining categories.
* As a general rule, categories should not overlap - users should see only one option that fits when making a selection.
* Categories and what would fall within them should be clear to those who will be collecting data. Training and information sessions may be critical for ensuring that project participants know how to gather data in consistent ways, but clarity and simplicity in configuration authoring goes a long way.
* The space available to display category names is limited, especially in Mapeo Mobile, so names should be generally be brief.
## Generating category files
All information you define for categories will be formatted in `JSON` in the [Coding configuration](/complete-reference-guide/customization-options/custom-configurations/creating-custom-configurations/coding-configuration) process, detailed in the following section.
{% hint style="info" %}
If you are not comfortable working with JSON, this information can be be passed off to someone with technical skills to complete the steps in [Coding configuration](/complete-reference-guide/customization-options/custom-configurations/creating-custom-configurations/coding-configuration).
{% endhint %}
# Icons
## What is an icon?
Each of the categories you include in your configuration needs to be assigned an icon, or a small graphic to display to users when selecting a category. You can assign the same icon to various cateogries, or each category can have it's own icon.
### How icons are viewed in Mapeo
Categories list with icons in Mapeo Mobile (using the default configuration):\
\
Examples of the icon files from our default configuration can be found [here](https://github.com/digidem/mapeo-default-config/tree/master/icons).
## Considerations when designing icons
Though creating the `.svg` icon files requires some knowledge of image editing tools, sketching and brainstorming ideas for icons can be a great way to involve community members and project participants who may not have technical skills. With paper and pencils, groups can come up with ideas for icons to represent each category in your project.
If you're not up for designing your own icon images, there are libraries of images online with Creative Commons licenses that you can draw from.
### **When designing icons, keep in mind the following:**
* Icons are displayed as very small images in Mapeo Mobile (24x24px) and Mapeo Desktop (100x100px). Very simple designs with minimal detail will render more clearly to users.
* When thinking about size and scale, imagine drawing your icons with a marker on a dime.
* Bold and solid-color lines and shapes will be most clearly visible.
## Generating icon files
Once you've settled on the design or concept for your icons, you'll need to generate `.svg` files required to include as part of the [Coding configuration](/complete-reference-guide/customization-options/custom-configurations/creating-custom-configurations/coding-configuration) process.
To do so, you can use our online Mapeo Icons Generator, [here](https://icons.earthdefenderstoolkit.com/).
Or, jump to [Creating and exporting SVG files using Adobe Illustrator](/complete-reference-guide/customization-options/custom-configurations/creating-custom-configurations/coding-configuration/adding-icon-files/creating-and-exporting-svg-files-using-adobe-illustrator) or [Creating and exporting SVG files using Inkscape](/complete-reference-guide/customization-options/custom-configurations/creating-custom-configurations/coding-configuration/adding-icon-files/creating-and-exporting-svg-files-using-inkscape) for technical guidelines in generating your own suitable SVG files.
{% hint style="info" %}
If you do not have skills to prepare the digital icon files, paper sketches can be passed off to someone with technical skills to complete the steps of generating icon files, outlined in [Coding configuration](/complete-reference-guide/customization-options/custom-configurations/creating-custom-configurations/coding-configuration).
{% endhint %}
# Details fields
## What are details fields?
For each category in your configuration, you can include one or more structured data fields (like a mini form or questionnaire) that users can optionally fill out when creating a new observation or map element with that category.\
\
Details fields can be text fields (type in your own answer) or multiple choice (select one or select many from a set of pre-defined answers).
### How details fields are viewed in Mapeo
Details field screen displayed during data collection with Mapeo Mobile:
## Considerations when defining details fields
When planning your data structure, you should think through which (if any) details fields you would like to include for each category. The same details field can be used for many categories.
For each details field you would like to include, you'll need to define the following:
* **Label**\
The primary text to be displayed to users ("Name" in the above image).
* **Placeholder**\
A hint or subtext that can clarify the field to users or provide guidance on how to use it ("Common name of this place" in the above image).
* **Field type**\
How users will be able to enter information for the field or question.
* `Text` or type in your own answer (Pictured in the image above)
* `Select one` from a list of options
* `Select multiple` from a list of options
* **Options**\
For `Select one` and `Select multiple` fields, you will need to define a list of possible answers to display.
### **When defining details fields, keep in mind the following:**
* It can be very challenging for users to type in detailed information when collecting data in the field. Users may be under significant stress, in risky situations, or interacting with the Mapeo screen in bright sun or rain. When creating `Text` fields, keep in mind the conditions users will be facing and have reasonable expectations for the amount of detail and work required to fill out your details fields.
* If there are a consistent set of answers you can anticipate for a field or question, it can be much faster or easier for users to select from a list as part of a `Select one` or `Select multiple` field. Please note that there is no automatic option for typing in information for "Other" or an option not included in the list.
* It may be very clear to you when authoring your configuration what each details field means or intends to communicate. Keep in mind, however, who will be collecting data as part of your project and how they might read or interpret each field. Very clear and explicit language can go a long way towards ensuring your configuration is used as intended.
* Mapeo Desktop currently allows you to filter observations by options in `Select one` fields. To filter by options in `Select multiple` or `Text fields`, you will need to export your data and view it in another software tool.
## Generating details field files
All information you define for details fields will be formatted in `JSON` in the [Coding configuration](/complete-reference-guide/customization-options/custom-configurations/creating-custom-configurations/coding-configuration) process, detailed in the following section.
{% hint style="info" %}
If you are not comfortable working with JSON, this information can be be passed off to someone with technical skills to complete the steps in [Coding configuration](/complete-reference-guide/customization-options/custom-configurations/creating-custom-configurations/coding-configuration).
{% endhint %}
# Coding configuration
Mapeo configuration files (`.mapeosettings`) are compiled from a set of files and folders that contain all the information Mapeo needs to display the categories, icons and details fields you want users to see when collecting and viewing data. This section will walk you through translating all of the information you've defined in [Planning configuration & data structure](/complete-reference-guide/customization-options/custom-configurations/creating-custom-configurations/planning-configuration-and-data-structure) into a Mapeo configuration file.
### Configuration folder structure
To begin preparing your files, you can download or clone our [**default configuration repository**](https://github.com/digidem/mapeo-default-config) or this [**empty configuration repository**](https://github.com/digidem/empty-mapeo-config) from GitHub. These repositories contain the core files and folders you will need for editing.
When authoring custom configurations, you will edit files within the following configuration **folders**:
* **`icons`**
* **`fields`**
* **`presets`** (categories)
And the following configuration **files**:
* `metadata.json`
* `defaults.json`
* `package.json`
## Prepare folder structure
### Using the file explorer
1. Download the [default configuration repository](https://github.com/digidem/mapeo-default-config) or [empty configuration repository](https://github.com/digidem/empty-mapeo-config).
2. Unzip the contents to a new folder using a program like [7zip](https://www.7-zip.org).
3. Rename the folder from "mapeo-default-settings" to use your own project name, "mapeo-config-projectname".
### Using the terminal (linux and mac)
```
wget https://github.com/digidem/mapeo-default-settings/archive/v2.1.0.zip
unzip v2.1.0.zip
mv mapeo-default-settings-v2.1.0 mapeo-settings-myprojectname
```
# Adding icon files
{% hint style="info" %}
To review key information on designing icons, see [Icons](/complete-reference-guide/customization-options/custom-configurations/creating-custom-configurations/planning-configuration-and-data-structure/icons).
{% endhint %}
Once you've settled on the design or concept for your icons, you'll need to generate `.svg` files for each one to be saved in the **icons** directory. Icons should be created as 100x100 pixel graphics that are clear when viewing at 100%.
To generate `.svg` icons for Mapeo, there is an online Mapeo Icons Generator tool accessible [here](https://icons.earthdefenderstoolkit.com/).
We have also documented two workflows to generate Mapeo-compatible `.svg` files using software, one using a commercial product (Adobe Illustrator) and another using a open-source product (Inkscape).
* [Creating and exporting SVG files using Adobe Illustrator](/complete-reference-guide/customization-options/custom-configurations/creating-custom-configurations/coding-configuration/adding-icon-files/creating-and-exporting-svg-files-using-adobe-illustrator)
* [Creating and exporting SVG files using Inkscape](/complete-reference-guide/customization-options/custom-configurations/creating-custom-configurations/coding-configuration/adding-icon-files/creating-and-exporting-svg-files-using-inkscape)
## Naming icon files
Icons need to be read by MAPEO in two sizes: 100 pixels and 24 pixels. For that reason there is a specific file naming convention:
* *icon-name*`-100px.svg`
* *icon-name*`-24px.svg`
Each icon can be duplicated and renamed so that there is one of each size. They are opened and read by the `.json` files in the **presets** folder. Verify that `name` is correctly entered where needed (more on this in the next section). The build script will process the pixel size suffix.
## Additional resources
* [Troubleshooting SVG image errors in Mapbox Studio](https://docs.mapbox.com/help/troubleshooting/studio-svg-upload-errors/)
# Creating and exporting SVG files using Adobe Illustrator
[Adobe Illustrator](https://www.adobe.com/products/illustrator.html) is a vector graphics editor and design program developed by Adobe Inc. Although it is a commercial, licensed product, it is very commonly used to put together vector graphics, and many users utilize this tool for creating icons for Mapeo as well.
### Exporting `.svg` files with the right properties
When you're ready to export a vector graphic file into a Mapeo-compatible `.svg` file format, the process is as follows:
* On the Adobe Illustrator top menu, click on **File** and then select **Export,** followed by **Export As.**
* Ensure that **Use Artboards** is checked.
* Save your `.svg` file in the correct directory (**`icons`** for Mapeo configurations) and with your desired filename, and click **Export**.
* In the following window, ensure that the following properties are set, and then click **OK**:
Your `.svg` file should now be ready to be used by Mapeo. See [Adding icon files](/complete-reference-guide/customization-options/custom-configurations/creating-custom-configurations/coding-configuration/adding-icon-files#naming-icon-files) for more information on how to name the files and where to place them in the configuration directory.
# Creating and exporting SVG files using Inkscape
[Inkscape](https://inkscape.org/) is a free and open-source vector graphics editor used to create vector images, primarily in Scalable Vector Graphics (`.svg`) format. Inkscape is an alternative to the commercial software Adobe Illustrator, and can be used to generate `.svg` files that work in Mapeo.
### Using Inkscape to vectorize images
A common workflow for generating Mapeo icons is to find photos or other raster images, and turn them into vector images, simplifying them until they will render well at a small size. In Adobe Illustrator, this can be done using the `Image Trace` tool.
In Inkscape, this can be done using the `Trace Bitmap` tool found in the Path menu. There are some options to manipulate like Smoothing corners, Optimizing corners, and setting the number of colors.
### **Saving `.svg` files with the right size and Viewbox in Document Properties**
Once you have a vector image that is to your satisfaction (and in a square format), you need to set the correct width & height and Viewbox size before saving the `.svg` file. You can do this in `Document Properties` (**File** menu).
First, set the `Display units` to pixels (px). This dropdown is located at the very top of the Document Properties menu.
Locate the "Custom Size" and "Scale" boxes in Document Properties.
First, you may need to set the unit of measurement for the Custom size, if it is not in pixels. If `Units` is in a format like milimeters (mm), change this to px.
Set the `Width` and `Height` to 100 each.
Next, the Viewbox needs to be set to 100 as well. The easiest way to do this — once you've set the Display units and Custom size units to pixels — is to set the `Scale x` to 1. It should copy over the Width and Height values from the Custom Size to the Viewbox. If that didn't do the trick, manually enter 100 for both `Width` and `Height` here.
Once you've done this, you may need to resize the art to match the full size of the Viewbox:
The easiest way to do this is to use the sizing and placement parameters right above the Viewbox, as shown in the screenshot above. Set `W` and `H` to 100 (px), and make sure `X` and `Y` are set to 0 (px). The image will then fill the entire Viewbox:
You can now save the `.svg` file by going to File → Save / Save As / Save A Copy.
Your `.svg` file should now be ready to be used by Mapeo. See [Adding icon files](/complete-reference-guide/customization-options/custom-configurations/creating-custom-configurations/coding-configuration/adding-icon-files#naming-icon-files) for more information on how to name the files and where to place them in the configuration directory.
### Verify that your SVG file is built correctly
{% hint style="info" %}
If you want to verify that the parameters in your `.svg` file are correct, open it in a text editor like Visual Studio Code or Notepad++.
{% endhint %}
It should have an initial `
**Mapeo Mobile**, you can collect geographic points to mark your current location, and add associated photos, description, and details. Users assign each point collected to a category. Check out the [Mapeo Mobile Quick Start Guide](/quick-start-guide/mapeo-mobile) to see an overview of mobile data collection.
With 
**Mapeo Desktop** Territory mode, you can create points, lines and areas (polygons) on a map and add an associated category, description, and details.
For more on Mapeo's default categories and details fields, see [Default configuration](/complete-reference-guide/will-mapeo-work-out-of-the-box-for-me/default-configuration). To learn about customizing these options, see [Custom configurations](/complete-reference-guide/customization-options/custom-configurations).
## What languages is Mapeo available in?
Mapeo is currently available in over 8 languages, including:
* English
* Spanish
* Portuguese
Mapeo can be translated into additional languages on [Crowdin](https://crowdin.com/). For more information, see [Translating Mapeo & default configurations](/complete-reference-guide/customization-options/translating)
## Is Mapeo Mobile available for iOS?
Mapeo Mobile is currently available for Android only. It is on our roadmap to release a version for iOS in the future.
## Do I need to customize Mapeo to use it?
When you install Mapeo, it comes with default options that can be used right away, without any customization. To learn more about whether these options will work for you, see [Will Mapeo work out-of-the-box for me?](/complete-reference-guide/will-mapeo-work-out-of-the-box-for-me)
Some projects may require customization of data fields or background maps in order to best meet the needs of the project or context. Customization currently requires some technical skills. For more on customization options and technical requirements, see [Customization options](/complete-reference-guide/customization-options).
## How does Mapeo work offline?
Mapeo is built on an embedded peer-to-peer database, so all data collected with Mapeo is stored directly on your device, with no need for an internet connection or centralized server. Users of Mapeo Mobile and Mapeo Desktop can synchronize or exchange data over a local Wi-Fi network. The data never leaves your local Wi-Fi network and does not require an internet connection. Mapeo Desktop can also exchange information via a synchronization file using a USB drive.
For more on how Mapeo stores and synchronizes data, see [Peer-to-peer & Mapeo sync](/overview/about-mapeo/peer-to-peer-and-mapeo-sync).
## Does Mapeo use a Blockchain?
Mapeo uses secure peer-to-peer technology with a distributed ledger, which does not include a public blockchain or consensus.
Public blockchains are designed for a scenario where public transactions must be mediated between participants which are all potentially malicious. These “trustless” transactions are the key assumption of a blockchain that distinguishes it from peer-to-peer technology.
Applications like Mapeo assume that data is managed by the community generating it - and **some of that data may never be publicly accessible.** Mapeo's approach, in contrast, creates a closed group, where data creators are also data stewards, managing their own data and controlling who has access. We take security seriously and maintain protections from third-party attacks such as targeted hacks and surveillance by third-parties. For users of Mapeo, privacy is critical for protecting their ancestral knowledge and environmental monitoring information until it’s ready to be shared with trusted partners.
For more information, [read this blog post](https://wp.digital-democracy.org/cooperative-ownership-of-data-without-blockchain/) and [this paper from Article 19](https://www.article19.org/resources/blockchain-technology-alone-cannot-protect-freedom-of-expression) about why blockchain is not a recommended tool for human rights and freedom of expression.
## Who will have access to my data?
Mapeo was designed to be an offline-first set of tools that centers data sovereignty for its users. That means that the data you collect with Mapeo will only exist on the device it is collected or created with until you choose to share it with other Mapeo project participants or external actors. The data you create will never be stored on external servers or shared with app maintainers or other actors, unless you choose to send it or enable and use Web sync options through Mapeo.
## Does Mapeo collect information on users?
Mapeo collects only basic, anonymized statistics for debugging, designing and understanding to what extent the applications are being used.
## What happens if Mapeo loses financial support? **Will my data be inaccessible?**
Mapeo is built with long-term sustainability as a focus. This goes beyond financial sustainability - we ensure that no single entity or technology is responsible for data storage or access.
Mapeo does not lock your data into a particular data format. You can easily move your data around, and it is kept in its original form. Mapeo Desktop can export data to [SMART](http://smartconservationtools.org/download/), Shapefile, CSV, and GeoJSON. You'll never be locked into using Mapeo software. For more on export options, see [Exporting data & sharing externally](/complete-reference-guide/mapeo-desktop-use/using-mapeo-desktop-to-manage-mapeo-mobile-data/exporting-and-sharing-externally).
## Can you help me deploy Mapeo?
There is a community of active users and maintainers of Mapeo that participate in our public chat channel on [Discord](https://discord.gg/KWRFDh3v73) and on our [Earth Defenders Toolkit Forum](https://forum.earthdefenderstoolkit.com/). We encourage you to consult these spaces for additional tips and ideas on how people are using Mapeo.
Digital Democracy's core team is very small and we have limited capacity to provide direct accompaniment for implementing Mapeo outside of our existing partnerships. In some cases we are able to offer support. To read more about the way we work with partners and different levels of support, see [here](https://drive.google.com/file/d/1c9C1-6v1EHKnfrYDsBn3VNu5qS_pUNMC/view?usp=sharing).
## How can I report bugs or problems using Mapeo?
There is community of active users and maintainers of Mapeo that participate in our public chat channel on Discord. To join the conversation or seek help on technical issues, you can [access the channel here](https://discord.gg/KWRFDh3v73).
# Getting started
The **Quick Start Guide** is intended to help you install and test the basic, out-of-the-box functionality of Mapeo in order to evaluate whether it will be a good fit. This section will not touch on all features or customization of the tools.
The [**Complete Reference Guide**](/complete-reference-guide/welcome) below includes critical information about how to design and implement a project using Mapeo as well as detailed guides for setup and customization of the tools. We recommend using it for starting a new initiative or as a training reference.
# Mapeo Mobile
## Install
To install Mapeo Mobile on your Android device,[ download the latest version on Google Play](https://play.google.com/store/apps/details?id=com.mapeo\&hl=en_US). You can also [download the app as an APK ](https://apk.mapeo.app/latest/)and install it manually on your phone. For more on installation, see [Installing Mapeo Mobile](/complete-reference-guide/mapeo-mobile-installation-setup/installing-mapeo-mobile).
## Collect data
You collect data with Mapeo Mobile in the form of *observations*. An observation is based on a geographic location (a point on the map) and can have associated photos, notes and details.
To create a new observation, tap the 
**Create observation** button, then select a category.
 
Add a description, photos and details, then tap the 
**Save** button.
## View observations
Each observation will be marked on the map with a dot. Observations can also be viewed in list form by tapping the 
**Observations list** button.
 
Tap on an observation from the map or list to view its details.
## Edit an observation
With the details of an observation open, tap the 
**Edit** button to make changes.
## Share data externally
Tap on the 
**Share observation** button to send the details of a single observation to a contact outside of Mapeo using one of the communications apps installed on your phone (WhatsApp, Signal, Email, etc.).
## Delete an observation
Tap the 
**Delete** button to delete an observation and its associated media.
{% hint style="warning" %}
Deleting observations cannot be undone, so exercise caution when using delete.
{% endhint %}
## Synchronize data
Mapeo Mobile allows you to synchronize data with other Mapeo users that are participants of the same project. During synchronization, ALL data from one device will be sent to the other device and vice versa. For more on synchronization, see: [Peer-to-peer & Mapeo sync](/overview/about-mapeo/peer-to-peer-and-mapeo-sync).
To synchronize data between 2 Mapeo Mobile devices that are near each other:
1. Connect both devices to the same Wi-Fi network. (You do not need to have an internet connection.)
2. Tap the 
**Synchronize** button on both devices.
3. On the **Synchronize** screen, identify the device you wish to synchronize with in the list and tap the **Sync** button beside its name.
4. Keep the **Synchronize** screen open on both devices until the synchronization has completed.
{% hint style="info" %}
For detailed instructions on how to use all features of Mapeo Mobile, see below sections in the Complete Reference Guide:
[Mapeo Mobile installation & setup](/complete-reference-guide/mapeo-mobile-installation-setup)
[Mapeo Mobile use](/complete-reference-guide/mapeo-mobile-use)
{% endhint %}
# Mapeo Desktop
## Install
Download Mapeo Desktop from the [Mapeo website](https://www.digital-democracy.org/mapeo/) and double click the file to launch the installer. For more on installation, see [Installing Mapeo Desktop](/complete-reference-guide/mapeo-desktop-installation-setup/installing-mapeo-desktop).
## Mapeo Desktop for managing Mapeo Mobile data (Observations mode)
**Observations** mode in Mapeo Desktop is designed for viewing, managing and exporting data collected with Mapeo Mobile. The steps below will cover the basics for testing **Observations** mode.
{% hint style="info" %}
For more detailed instructions and information on how to use Mapeo Desktop for creating territory data (**Territory** mode), see the Complete Reference Guide section on [Mapeo Desktop use](/complete-reference-guide/mapeo-desktop-use).
{% endhint %}
## Synchronize Mapeo Mobile data
To get started, synchronize collected data from a Mapeo Mobile device. To synchronize via Wi-Fi, as detailed below, the Mapeo Mobile and Mapeo Desktop devices must be near each other.
### Connect to Wi-Fi
Make sure both the 
button below its name.
{% hint style="warning" %}
**IMPORTANT**: Keep the **Synchronize** screen open on BOTH devices until the synchronization is complete. Interrupting the sync process can result in permanently corrupted data.
{% endhint %}
{% hint style="info" %}
In order to synchronize, Mapeo devices must be connected to the **same Wi-Fi network**, and using the **same project configuration**.
For more detailed instructions on synchronizing in Mapeo Desktop, see [Synchronizing data](/complete-reference-guide/mapeo-desktop-use/using-mapeo-desktop-to-manage-mapeo-mobile-data/syncing-data).
{% endhint %}
## View observations
To view synchronized data, click on **Observations** in the **Mapeo modes** panel.
### Map view
By default, observations are displayed as dots on a map. Click on an individual dot to view the details of that observation.
### Media view
To view observations as a gallery of images, click on **Media** in the **Toolbar** above the map. Click on an individual image to view the details of that observation.
### **Report view**
To view observations in the form of a report, click on **Report** in the **Toolbar.**
## **Filter observations**
To look at a subset of your observations in **Map**, **Media** or **Report** view, use the **Filter** panel to select a specific data range, a subset of categories, or specific data values from details fields.
## **Edit observations**
From **Map** or **Media** view, click on a dot or image to view the full details of the corresponding observation. From **Report** view, use the 
**EDIT** button in the grey toolbar to open the details of the observation shown in the current page of the report.
With the observation details open, click on a field to add or edit information. Click **SAVE** to save changes.
{% hint style="info" %}
In Mapeo Desktop you cannot modify the creation date, category type or geographic location of an observation.
{% endhint %}
## Delete observations
To delete an observation, open the observation details and click on the
**More options** menu. Select **Delete observation** and confirm deletion in the pop-up window.
{% hint style="warning" %}
**Deleting observations cannot be undone, so exercise caution when using delete.**
By deleting observations, you will permanently remove them from your device and all devices you synchronize data with in the future. For more on synchronization, see [Peer-to-peer & Mapeo sync](/overview/about-mapeo/peer-to-peer-and-mapeo-sync)
{% endhint %}
## Export data
Data can be exported to multiple formats from **Observations** mode in Mapeo Desktop. Basic export instructions are included below.
* [Save as PDF Report](#save-as-pdf-report)
* [Export to GeoJSON, CSV, or SMART CSV](#export-to-geojson-csv-or-smart-csv)
* [Export as Web Map](/complete-reference-guide/mapeo-desktop-use/using-mapeo-desktop-to-manage-mapeo-mobile-data/exporting-and-sharing-externally#export-as-web-map) (In Complete Reference Guide)
{% hint style="info" %}
For more details on Mapeo export formats and process, see [Exporting data & sharing externally](/complete-reference-guide/mapeo-desktop-use/using-mapeo-desktop-to-manage-mapeo-mobile-data/exporting-and-sharing-externally) in the Complete Reference Guide.
{% endhint %}
### **Save as PDF Report**
To save a PDF report with the observations collected, go to **Report** view. Filter observations if desired using the **Filter** panel. Hide any fields you don't wish to appear by using the 
**Hide fields** option in the grey panel above the report.\
\
To save, click on 
**Save PDF.**
### Export to GeoJSON, CSV, or SMART CSV
To export observations to GeoJSON, CSV or SMART CSV format, click on the 
**Export options** menu at the top right corner of the Mapeo Desktop window.
Select **Export Observations...** then select the desired data format and options in the Export Observations pop-up window. Click **SAVE** to name the export file and choose the location on your computer where it will be saved.
{% hint style="info" %}
For detailed instructions on all features and uses of Mapeo Desktop, see [Mapeo Desktop use](/complete-reference-guide/mapeo-desktop-use) in the Complete Reference Guide.
{% endhint %}
# Welcome – Introduction
Welcome land defenders, community mappers, resource and impact monitors, data collectors, students, scientists - whoever you are, we hope you have enjoyed playing around with Mapeo using the Quickstart guide above.
If you think that Mapeo might be the right tool for your project, this **Complete** **Reference Guide** is designed to provide you with learning and training materials, suggested workflows, and some examples of real projects in order to help get you set up and using Mapeo in the best possible way for your needs.
There is a LOT of information in the sections below, and there are many different ways of using Mapeo. We don't expect users to make use of every Mapeo feature nor need to read every section, but we do hope that what we are providing here can help users be well informed about technical details that will impact your projects.
# Essentials for a successful Mapeo project
In the pages below you'll find a collection of resources to support in getting a Mapeo project started.
* [Planning a Mapeo project](/complete-reference-guide/essentials-for-a-successful-mapeo-project/planning)
* [Security & risk assessment](/complete-reference-guide/essentials-for-a-successful-mapeo-project/security-and-risk-assessment) (Coming soon)
* [Creating user protocols](/complete-reference-guide/essentials-for-a-successful-mapeo-project/creating-user-protocols) (Coming soon)
Additional information on running trainings in Mapeo can be found in [Mapeo trainings](/complete-reference-guide/training-and-information-sessions).
# Planning a Mapeo project
You may be keen to jump in and get started with data collection, however spending a bit of time upfront thinking through how the project will run, the methodology, team set-up, logistics of gathering data, and how the data collected or created with Mapeo will be used can save you a lot of time and avoid problems and issues later on.
This guide does not aim to give you a blueprint of how to run your project. There are so many different uses of Mapeo, some of these we (Digital Democracy) can imagine, some of them we can't, and each one has its own particular needs, priorities and local contexts. What works in one place might need to be set up very differently for another place, even if the desired outcome is very similar. And likewise what works somewhere at one time, might have to be adjusted for another time as local situations, politics, etc. change.
Hopefully spending time thinking through the questions below will enable you to create a process tailored to your needs and project, and give it the best possible chance of success.
**We are going to run through the following questions:**
* [**Why collect information?**](/complete-reference-guide/essentials-for-a-successful-mapeo-project/planning/why-what-is-the-project-goal) What is the aim of your mapping, monitoring or data collection, what is your goal or desired end product or result?
* [**What outputs do you want?**](/complete-reference-guide/essentials-for-a-successful-mapeo-project/planning/what-outputs-do-you-want) If you already know that you want to build an interactive story map, or produce a quantitative report or file a legal case, this can help shape your project design.
* [**What information do you need to collect in order to meet this aim?**](/complete-reference-guide/essentials-for-a-successful-mapeo-project/planning/what-information-to-collect)
* [**Who should be involved?**](/complete-reference-guide/essentials-for-a-successful-mapeo-project/planning/what-are-your-parameters) What project structure will best meet your aims, who should be involved, what roles do you need, who is making decisions and who are you accountable to?
* [**What are the parameters or limiting factors you are working with?**](/complete-reference-guide/essentials-for-a-successful-mapeo-project/planning/who-is-involved) This refers to your geographical context, infrastructure, accessibility to areas, budgets and equipment availability, time constraints, security risks, etc.
* [**Is Mapeo the right tool for you?** ](/overview/is-mapeo-right-for-me)We think Mapeo is great :) but we know that it has limits and it isn't the right tool for every job. We want to make sure that if you choose Mapeo you understand what it excels at doing and also its weaknesses, to make sure you are set up in the best possible way for success in your project.
### Provisos
Mapeo was co-developed with community land defenders in the Amazon. We have tested, piloted and received feedback on it from people around the world using it for a variety of purposes, and we hope it can serve a wide range of needs. However it is built with the needs of land and rights defenders at its heart, and therefore this guide, and many of the materials produced for Mapeo are also built with these needs at the forefront.
In part because of its design process, and the partners with whom Digital Democracy has worked, we often refer to **community** and **collaborative** processes. Mapeo can definitely also be used by individuals, and a variety of different teams, but many of our partners are using it in local, frontline community contexts, and so the language of this guide centers them. We also understand that communities are not homogenous and mean different things in different places, and hope that you can read between the lines where necessary to extract the useful parts of this guide for whatever it means to you.
This guide draws on work from our team over the last two decades in indigenous and community land rights and defense. However indigenous and marginalized communities have been defending their land for centuries. There are many projects and initiatives from which the development of Mapeo and the methodologies suggested here have been guided, received inspiration and learned. This reference guide does not aim to provide an exhaustive list of such projects, but at the end of the guide there is a Reference Section which highlights some materials from other sources and initiatives which may be of help to you in planning your project.
All the examples included in the guide are just that, examples. We hope they are helpful and provide some context and illustration to the processes described, but are not intended to be taken and copied as 'out of the box' methodologies. As we hope this planning section will describe, context is everything, and methodology should be carefully considered and adapted to best fit the needs of the project and particular community context.
# What is the project goal?
Why collect information? What is the aim of your mapping, monitoring or data collection, what is your goal or desired end product or result?
So you want to start collecting information, perhaps you are going to be making a map, or perhaps you want to collect evidence of impacts on your land or gather other data or information. The first question to clearly ask of yourself or your community is **WHY? What is it that you hope to gain or change or learn through the project?**
The more detailed an answer you can give to this question the better set up you can get; making sure anyone involved in the project is working towards the same goal and being able to determine the best methodology for meeting it.
For example, if you want to make a map – what is your map for, what impact do you want it to have for you, your team, in the world, etc. Perhaps the map is the end product, or perhaps just one step in a longer process, or maybe the main aim is building relationships, and the map is the means to bring people a focus for working together.
**What if you don't know yet?** Perhaps you know you want to gather data about something that interests you but are not yet sure how you are going to use it. Don't worry, you can refine your aim and build on your project as you go along and learn more.
And remember - all plans change and it is impossible to predict everything in advance. There will be unforeseen outcomes, some beneficial, some possibly challenging, of your project. However having your main goal in mind as you begin to plan your methodology and define what information you are going to collect sets you up to meet any challenges, and welcome any positive changes, in the best way.
# What outputs do you want?
It might be too early to start thinking about outputs, but if you already have a sense of what these might be then they might give some useful direction to your planning process. By output we don't mean the goal or results of your project, although these might overlap, we are referring particularly to concrete materials that result from your Mapeo project.
For example these could be:
* **Printed map / maps:** These might be for an external audience such as the government or a legal body, or they might be for the community itself to use for other purposes. If you are planning on creating a map then consider what information you can show on the map - perhaps you spend a long time collecting stores which then are hard to find space for, or you collect so much information that the map is hard to read.
* **Data reports:** You might want to produce regular reports on the data you collect, or wait until the end of your project and then produce a report with all the data or the highlights. Do your reports include quantitative data that you want to analyse and present in a particular way or is it mainly qualitative data that will need editing or compiling before presentation. Thinking about these can help you to organise your teams and data collection so that you have the data when you need it, in the right format.
* **Alerts:** If you are collecting evidence of something that needs fast action then having an alert system built into your methodology could help. Mapeo Mobile can export datapoints to WhatsApp and other apps so you could potentially send alerts of illegalities straight to law enforcers for immediate action.
* **Interactive webmap:** This could be a good output if you are hoping to build a campaign and want to share some of the project with the public or media - or even for your own community such as for an educational or storytelling resource. It also enables different kinds of information to be present than on a printed map as you can include videos and audio more easily. However it may involve a level of technical expertise or budget beyond the scope of your project, and it is definitely not the right output for every goal.
***
# What information to collect?
When you have clarified the main goal for the project, the next step is to think through carefully what data you want to collect or create. This will not just be dependent upon the final goal, but also on other factors such as the time and funding available, the security situation, and any legal guidelines. So it may be a good idea to read this section again after reading the "What are your parameters" section.
Depending on your needs and capacity you may find that the default configuration and categories that come with Mapeo do the job well enough, or you might want to set up a custom configuration with your own icons and questions tailored to your specific needs. For more on how to do this, see [Creating custom configurations](/complete-reference-guide/customization-options/custom-configurations/creating-custom-configurations)**.** Perhaps, if your project is new and you are still figuring out what is needed, you may want to start collecting data using the default configurations, and learn from that process about what categories and questions you really need.
The simple answer to the question of what information to collect is probably quite obvious from your goal, but when you dig down the answer isn't always that easy. So if you need a territory map for a land claim then you probably need to collect information about territory use, as well as the territory boundaries or limits - but exactly what information do you need, what format should it be in, how much detail do you need, etc. And if you want to collect evidence of illegal gold mining, then you may want to collect georeferenced photos and answer a series of questions about the scale and nature of any impacts found, but what is the best way of framing questions to get you the answers your community and perhaps legal team need to evaluate what is going on and how to take action, and what should you be taking photos of exactly?
Collecting data can be a time-consuming and expensive process, and can raise expectations about outcomes. So thinking this through carefully in advance will help ensure you are a) not wasting your own or others time and resources collecting information that isn't going to be useful and b) not in the situation where you realize at the end of a month-long trip that you need to go back to all the places again because you forgot to collect a crucial bit of data.
Think about the following questions to further clarify exactly what data you should be gathering and how to set up any custom configurations:
* **First think about your goal** and what you know of your needs. Brainstorm with any other team members or with the community about all the possible things you could collect information about, categories and questions, and then start organizing and refining.
* **If possible do some research by talking to allies**, or looking online to see how other similar projects were set up and what data they collected.
* **Are there any rules, restrictions or guidelines** that might determine the kind of information you collect and how to ensure it is usable. For example some governments/authorities might require data to be collected in a particular GPS format, or follow a particular information template, in order to be accepted or easily acted upon.
* **Might the data need to be used in a legal process**, if so there may be specific ways of collecting it, or additional questions you ask, which will enable it to be used more effectively. If possible get local legal advice about this, as it will differ depending on the type of data and the country you are in.
* **Knowing how much information is too much**. Once you start making a map or collecting information it quite fun... maybe a little too fun 🙂. If you have all the time in the world then this may not be a problem, but if people or lands are being threatened you may need to make compromises in terms limiting the data you collect to that which is urgently needed.
# Data types within Mapeo
There are two types of data that Mapeo stores in its database located on devices.
**Mapping data** is meant for generating data for map making or baseline territory information. Mapeo Mapping data can only be viewed, edited and exported with Mapeo Desktop in Territory view. Data collected using Mapeo mobile of GPS devices can be used as precise references for creating new mapping objects. Mapeo mapping data It stores the following information
* **Geometry:** Determines if the map object is a point, a line, or an area.
* **Coordinates:** (specific formate?)
* **Category:** A user selects from a list of categories each with a predefined name, icon, predefined tags and details fields
* **Icons:** Visible in Mapeo Desktop Territory when creating and viewing Mapping data.
* **Tags**: These are additional values to the predefined tags packaged in each category
* **Details** (optional): User filled fields that relate specifically to a category that may help with consistant quality of information
* **Date time of last edit:** This information is appended to each object as a log of changes that get's saved a the end of a mapping editing session for decentralized data consolidation.
**Observation Data** is meant to capture time based information at a specific coordinate with options to add photos and details captured in the field. Observations can only be created using Mapeo Mobile. Observation data can only be viewed, and edited in both Mapeo Mobile and Mapeo Desktop Observations, and each tool offers unique share and export options to output observation data. Mapeo Observation data stores the following information:
* **Geometry:** Observations are always captured as points, to replicate objective human observation when visiting a point of interest.
* **Coordinates:** Available in various formats for data collection. on Mapeo Mobile coordinates are captures automatically using the devices location detection hardware. Mapeo Mobile features include capturing the most precise GPS reading possible when device location is turned on. There is also a manual coordinate entry option is GPS precicion is low or unavailable. Coordinates cannot be edited after capture.
* **GPS metadata**: For forensic varilfication, GPS metadata including altutudem velocity and precision is in each observation captured with the devices GPS features. This information is currently not visible in the user interface.
* **Category:** A user selects from a list of categories each with a predefined name, icon, tags and details fields. These elements are packaged in each category and bases on common user needs. These can be customized \[link]
* **Icons:** Visible in Mapeo Mobile when creating observations and on observation viewing screens. Visible on Mapeo Desktop Observations in Report view
* **Tags**: These are predefined tags packaged in each category. This information is currently not visible in the user interface.
* **Details** (optional): User filled fields that relate specifically to a category that may help with consistant quality of information. In customized configurations add any number of questionscan be added for field surveys to collect quantitative information or evidence. Your questions can be text fields for open descriptions; select one or select multiple from a predefined list of options.
* **Date time of creation:** This information is fundamental to an observation and differenciates it from mapping data as time based data. In both Mapeo Mobile and Mapeo desktop observation data will displayed by Date/time of creation with newest first.
* **Date time of last edit:** This information is appended to each observation as a log of changes for decentralized data consolidation.
* **Photos**: (optional) Stil images can be captured by the Mapeo Mobile camera which automatically links the media files to the observation. \[is any GPS or camera metadata attached to photos?]
# Who should be involved and how?
What team structure will best meet your aims; who should be involved, what roles do you need; who is making decisions and who are you accountable to?
The answer to this question of who should be involved could vary wildly. Perhaps it is just you and your mobile phone, or perhaps it is going to involve thousands of people across multiple countries working together to compile a mass of data. Most of the partners we have worked with directly are somewhere in between, often a community or group of communities with a dedicated team of collaborating to collect data.
However even the projects we have partnered on directly, which might look superficially very similar, have set up their project structures in very different ways, sometimes out of need and sometimes out of preference. So here are some things to consider.
**Are there any traditional or other authorities that should be consulted before you start, or who should be involved in some role?** This is particularly relevant if you are collecting data from indigenous lands (your own or belonging to others) and/or might be collecting potentially sensitive data.
**Who is your project accountable to and how can you ensure you meet their needs?** The answer to this might be the traditional authorities mentioned above, or it could be particular sectors of your community, funders, the future generations or others. Consider how to keep them up to date with project progress if relevant and how to produce materials they will find accessible and useful.
**Do different members of your community hold different knowledge that you want to ensure is represented. How can you honour and involve these people and their knowledge?** Think here about women, elders and young people in particular, and how to ensure they are involved in the work and that they are not simply used to extract information from. Then depending upon the details of your project other groups might arise: traditional healers; skilled artisans; storytellers; health workers etc.
**Consider the ownership of the project:** If the project is meeting needs identified by your community, or collecting data intrinsic to them or their future consider how to ensure the community feels involved in the work and feels ownership over any results. Mapeo was built to try and facilitate community ownership of both projects and data by having a simple interface that could be explained to people without data collection training and people who might be non-literate or unused to computers or smartphones. Involving people at different stages of the project, including the planning phase can help increase this feeling of ownership, as can keeping the data locally, providing frequent feedback and reports back on what is happening, and creating outputs that people can use themselves or see at work.
**What other stakeholders or people with interest or authority do you want to involve?** Perhaps there are people who it would be useful to involve because they could help the project reach its goal such as local authorities, law enforcement, press, park rangers. Think about what role they might have in the project, whether they are consulted about things in advance or are simply informed and kept up to date with project progress. Consider too if there are people you want to keep the work and data secret from due to security or other considerations.
**Who is going to collect your data?** Unless yours is a solo project you are going to need to work with a team or teams of people to collect your data. This will be particularly necessary if you need to cover a large area of land, have time constraints or need different skills on your team. Think about the composition of the team and how you are going to build it - is it something people will volunteer for or will they be asked? Do you need to ensure diverse representation and if so how will you do this? Do you want to involve as many people as possible or have a small team that moves around?
**What other roles do you need?** If you are working with a team or teams of data collectors or mappers you are likely to need someone to coordinate them, help plan trips, collate the data they collect, analyse it and prepare any reports or outputs. This might be the role of a single coordinator, or you might need multiple ones due to the number of people involved or because of cultural or political sensitivities or the way the project ownership is set up. You might also have people involved in training, decision making, liaising with external bodies, helping with legal and communications work etc.
**What skills do people need?** We hope Mapeo is to learn and use, but if you are working in a team and want to collect comparable data people will need some training in how to use the app, and how to use it in the way your project needs. There might be other trainings necessary such as training in basic smartphone usage if people aren't accustomed to it; training in taking good photographs that illustrate what you want to show; training in gps; drones; video; audio recording; oral history recording; GIS software etc. conflict resolution, de-escalation etc depending on the details of your project.
**Create a project protocol:** Writing a protocol, if possible in a collaborative manner, which lays out any different roles within the project, their relationship to the data, agreements about use and ownership of data, any payments that are being made, what will happen to equipment and data at the end of a project etc. can be a way to keep things transparent and accountable and help avoid issues during and after the work.
# What are the parameters?
What are the parameters or limiting factors which you are working with? This refers to your geographic context, infrastructure, accessibility to areas, budgets and equipment availability, time const
No two Mapeo projects will look the same even if they have the same aims and are using the same configuration. There are so many factors which will influence how a project is run including timeline; budget; technology; landscape; seasons; climate; culture; social and political context; etc.
Whilst we can provide some ideas here, any project should be tailored to your particular context taking into account answers to the following questions. Thinking through these questions in advance will also be useful if you ask for help to put together a mapping project from an ally or other organisation.
#### **What is your timeline?**
Is there a particular urgency for the work, a date you need to produce a map or collect data by? If there isn't an internal deadline, are there significant dates external to the project that you might want to work towards or include within your calendar (eg. visits by authorities to the area, International meetings such as COP or UN Working Groups, World Social Forums etc.).
#### **What does the geographical landscape look like? What accessibility issues are there?**
Think about what the land looks like and how you plan to travel around. Some projects might be focused on a small area in town, where people can just travel around on foot on paved roads, other projects might cover tens of thousands of hectares and require travel by river, up steep hills, into swamps etc. Perhaps there are areas you want to access that are off limits (eg. National borders or Industrial installations can have no-go zones around them, or have rules about using GPS or drones etc) Drawing a quick sketchmap of the the area you plan to work within, and marking any significant landmarks, access routes, barriers etc. can help you plan out how you or your team is going to get around and how long this will take, and help identify any challenges you might encounter ahead of time.
#### **Do the seasons affect your work?**
If you plan to collect data at a particular time of year consider how the season or climate might affect this. For example the dry / rainy seasons might impact how easily you can move around the land, and might also impact the type of data you can collect (for example travel by river might be easier in the rainy season, but travel by road or foot might be harder); likewise some operations or activities you want to map or monitor might only occur at certain times of year (eg. illegal logging is linked to seasons, as are fruiting trees and fish/animal movements).
#### **Do you have a budget?**
Do you have or need a budget, and if so how much? Do you intend to pay people to take part or is it volunteer-led? If you don't already have a budget are there parts of the work that are going to need funds such as for purchasing equipment, travelling around or for any meetings you intend to hold.
#### **Do you have or need equipment for your project?**
Mapeo Mobile works on Android phones & tablets and Mapeo Desktop on Windows/Mac/Linux operating systems. Whilst essentially you might just need one smart phone for your project (which you might already have in your back pocket!), depending upon your plan, and particularly if you are going to work with teams in complicated environments you might need to think about other equipment such as spare battery packs if you are doing multi-day trips in remote areas; usb or hard drives for backups; trekking and medical kits for teams; waterproofing for tech that might be exposed to the elements etc., large sheets of paper, marker pens and notebooks for community workshops.
See equipment list for a list of things partners we have worked with have found useful.
#### What is the security situation?
Unfortunately, many frontline defenders are targeted for their work, often risking their lives to defend their peoples rights, lands and futures. Please consider your own safety and that of anyone else involved in the project and take what measures you can to identify risks ahead of time and mitigate them where possible, whilst doing the work that you need to do.
For example:
* Do you need to keep team members, or the names of people interviewed or otherwise involved in the project, or would it be better to involve the media and ensure there is a spotlight on the work?
* Are there places you can avoid going to and questions can avoid asking so as to not trigger dangerous responses?
* Do your teams need some kind of backup to keep them safe, a satellite phone, tracker or civil society accompaniment?
**Data security**
Sometimes it is not people that are at risk but data - consider therefore if you are collecting data that could be valuable to others and how you can best keep it safe.
Information can be sensitive in other ways too: perhaps only certain members of a community normally have access to it (but still want it documented) or perhaps it is information that the community does not want to make public.
Mapeo does not make any of your data public unless you choose to share it, you can create reports or export data which is filtered to exclude sensitive places or pieces of information, and you can share information with team members without it going online.
However there are other measures you can take to protect your information if needed, creating passwords for your devices ... what else?
# Security & risk assessment
{% hint style="info" %}
Coming soon
{% endhint %}
# Creating user protocols
{% hint style="info" %}
Coming soon
{% endhint %}
# Will Mapeo work out-of-the-box for me?
When you install Mapeo, it comes with default options that can be used right away, without any customization. In the following pages, this section details what is automatically included with Mapeo so you can determine whether the app will meet your needs out-of-the-box.
* [Default configuration](/complete-reference-guide/will-mapeo-work-out-of-the-box-for-me/default-configuration)
* [Default background map](/complete-reference-guide/will-mapeo-work-out-of-the-box-for-me/default-base-map)
Mapeo offers many options for customizing categories, icons, questions and background maps but the current customization process requires significant technical knowledge and will not be accessible to all users.
{% hint style="info" %}
For more on customization, see the following section on [Customization options](/complete-reference-guide/customization-options).
{% endhint %}
# Default configuration
### **About configurations**
Mapeo uses *configurations* to determine which categories, icons and questions users see when they are collecting data. For each data point collected with Mapeo, users select a category to classify the point, and may answer questions or respond to prompts to provide more detail about what is being documented.
### Mapeo's default configuration
When you install Mapeo, it comes with a default configuration that includes general categories and questions for territory mapping and monitoring.
#### Categories
The default configuration includes the following data collection categories:
Observations that do not fit these categories can always be collected using the **New point** category.
**Questions**
For every data point collected, users can enter a description of what they are documenting. Default categories also include some additional optional questions or fields that users may fill out when collecting data. For example, the category **Fishing Site** includes the field: ***Name** (Common name of this place*).\
\
 
To review all fields included in the default configuration, install Mapeo and explore the **Add Details** section for each category.
### Beyond the default configuration
Mapeo offers the option to create custom configurations to fit the needs of specific projects. For more information on customization, see [Custom configurations](/complete-reference-guide/customization-options/custom-configurations).
# Default background map
### About background maps
Mapeo uses background maps to show users their current location in the mobile app and as a background for displaying data collected or created with Mapeo.
### Mapeo's default background map
By default, when the device has access to the internet, Mapeo Mobile and Mapeo Desktop in **Observations** mode use a detailed background map that includes geographic elements such as rivers and mountains, as well as some political and urban elements such as borders, cities, roads, and others.
If the device is not connected to the internet, the background map shown by default is much less detailed. In Mapeo Mobile, the offline background map shows country borders and the main water bodies. In Mapeo Desktop, there is currently no default offline background map.
**Online background** **map example**:
\
**Offline background map example**:
### Beyond the default background map
Mapeo offers the option to add a custom background map for use both offline and online. For more on creating and adding custom background maps, see [Custom background maps](/complete-reference-guide/customization-options/custom-base-maps).
# Customization options
Mapeo was built to be highly customizable and allow users to adapt its interface to meet the needs of specific projects. This section covers both translation of the application and the development of custom configurations and base maps in the pages below:
* [Translating Mapeo & default configurations](/complete-reference-guide/customization-options/translating) (novice, intermediate)
* [Custom configurations](/complete-reference-guide/customization-options/custom-configurations)(advanced)
* [Custom background maps](/complete-reference-guide/customization-options/custom-base-maps) (advanced)
{% hint style="warning" %}
Please note that the customization process for configurations and base maps currently requires significant technical knowledge and will not be accessible to all users.
{% endhint %}
# Translating Mapeo & default configurations
Mapeo aims to be accessible to a wide range of communities in their native languages, and to facilitate the process of translating the app and the [default configuration](/complete-reference-guide/will-mapeo-work-out-of-the-box-for-me/default-configuration) into new languages as needed.
While [developing custom configurations](/complete-reference-guide/customization-options/custom-configurations) currently requires significant technical knowledge, the process of translating Mapeo and the default configuration into a new local language can be an easier way to customize the tool for use in your project.
### Translation using Crowdin
Translations for Mapeo are handled through the [Crowdin](https://crowdin.com) platform. It is free to create an account on Crowdin and anyone can contribute translations to Mapeo for new or existing languages.
To begin translating, visit the project page for the area you would like to translate.
* [Mapeo Mobile](https://crowdin.com/project/mapeo-mobile)\
Text and titles for screens and buttons in the mobile app
* [Mapeo Desktop](https://crowdin.com/project/mapeo-desktop)\
Text and titles for screens and buttons in the dekstop app
* [Mapeo's default configuration](https://crowdin.com/project/mapeo-defaut-config)\
Names of data collection categories, and details fields
#### Viewing available languages
On the project home page you can view all languages currently available for the project and how complete translations are.
#### Adding a new language
If the language you wish to translate is not available on the project home page, contact the Project Owner (listed on the bottom right of the page) to request an addition to the list.
#### Contributing translations
To start translating, create an account with Crowdin, visit the relevant project home page, and select the target language. Click on **Translate All** to bring up all relevant text strings.
# Custom configurations
### About custom configurations
Custom configurations are a powerful tool for customization in Mapeo, allowing users to define specific categories, icons, and questionnaires for their projects. Custom category and questionnaire text can be written in any language that can be typed, ensuring that key parts of the Mapeo data collection interface can appear in the native language of the groups using it.
In the current version of Mapeo, configurations also contain a *project key* that allows participants of the same Mapeo project to synchronize data with each other and prevents synchronization with other devices.
### Creating custom configurations
If you have determined that Mapeo's [Default configuration](/complete-reference-guide/will-mapeo-work-out-of-the-box-for-me/default-configuration) will not suit the needs of your project, you have the option of authoring a custom configuration.
{% hint style="warning" %}
Creating custom configurations currently requires significant technical knowledge and will not be accessible to all users.
{% endhint %}
The customization process, detailed in [Creating custom configurations](/complete-reference-guide/customization-options/custom-configurations/creating-custom-configurations), requires comfort editing `JSON` files, generating `SVG` image files, and using GitHub Actions or installing and using `node` packages via the command line.
# Creating custom configurations
{% hint style="warning" %}
Please note that creating custom configurations currently requires significant technical knowledge and will not be accessible to all users.
{% endhint %}
### Overview of the process
There are several steps to creating a custom configuration that will require different skills and the involvement of different actors within a project. You should leave plenty of time prior to the intended start of data collection to allow for community consultation, testing, and iterations of your configuration.
While data structures in Mapeo can be modified during the course of a project, many changes over time can result in messy data outputs. It is worthwhile to test and refine your configuration to the extent possible before putting it into use for data collection.
Once you have completed this process, you will have a Mapeo configuration file (`.mapeosettings`) that can be imported and used in Mapeo Mobile and Destop.
The pages that follow will walk you through the key steps for authoring a custom configuration:
* [Planning configuration & data structure](/complete-reference-guide/customization-options/custom-configurations/creating-custom-configurations/planning-configuration-and-data-structure)\
This section will outline the key customizable elements in a configuration and some considerations when mapping out each area.\
\***No technical knowledge is required.**