GeoOccitania
| GeoOccitania | ||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Authors: | P. Brechet — IEO, Institut d'Estudis Occitans | |||||||||||||||||||
| License: | To be specified for the application source code | |||||||||||||||||||
| Status: | Private V1 test version | |||||||||||||||||||
|
Occitan toponymy and collaborative mapping | ||||||||||||||||||||
| ||||||||||||||||||||
GeoOccitania is a collaborative web application for adding Occitan-language data to OpenStreetMap and collecting recordings of place-name pronunciations. It is a programme by P. Brechet — IEO, Institut d'Estudis Occitans.
Current status: V1 is a private test version. It is available only for controlled testing and is not yet an open public service. The OAuth registration, rate limits, backup procedures, retention policy and permanent domain must be finalised before access is opened to a wider audience.
1. Overview
GeoOccitania provides a movable world map and loads only the OSM objects found within the currently visible map extent. Administrators configure themes, markers, Overpass queries and forms.
Written contributions are sent to OpenStreetMap immediately after the contributor confirms them. Review is retrospective: a verifier can inspect the resulting public OSM changeset, but approval by a verifier is not required before the edit is uploaded.
Audio recordings follow a separate path. They are stored by GeoOccitania under the CC BY 4.0 licence and are not uploaded to OpenStreetMap.
2. Intended users and prerequisites
Contributor
A contributor:
- signs in with an OpenStreetMap account;
- chooses a theme and a marker;
- completes the permitted fields;
- confirms and sends the tags to OpenStreetMap;
- may record or upload an audio file;
- may send a message to the GeoOccitania administrator.
Verifier
A verifier:
- reviews recent contributions;
- opens the corresponding OSM changeset;
- may contact the contributor through OSM messaging;
- listens to, validates or deletes audio recordings;
- uses existing OSM tools to comment on or correct a problem when necessary.
Administrator
An administrator:
- configures themes, markers, forms and zoom levels;
- assigns application roles;
- views the internal history;
- exports metadata and prepares backups.
Toponymic rules
Contributors are expected to know and apply the relevant toponymic rules before editing:
3. Basic workflow
- Choose a theme. Themes are listed alphabetically and may be marked as favourites.
- Pan and zoom the map. GeoOccitania loads only the objects in the visible map extent.
- Select a marker. Its colour and shape indicate the function defined by the theme.
- Complete the fields. Labels are in Occitan and the corresponding OSM tag names appear alongside them. Fixed and hidden values are added automatically.
- Send the written contribution or the audio recording. Written data is sent to OSM; audio is stored separately by GeoOccitania under CC BY 4.0.
4. Themes, markers and Overpass
A theme groups one or more markers. Each marker has:
- a functional name and description;
- a shape and colour;
- minimum and maximum zoom levels;
- a marker-clustering threshold;
- an Overpass QL query;
- a form describing the OSM tags that may be sent.
The query itself determines which objects are shown. GeoOccitania replaces the literal placeholder {bbox} with the visible map extent. Positive and negative tag selection belongs in the Overpass query; it is not a separate GeoOccitania option.
A generic query is:
nwr
["name"]
({bbox});
out center;
An active query must contain {bbox}. A large extent or a very broad query can overload an Overpass instance. Zoom ranges and clustering should therefore be adapted to object density.
Overpass is an external service. It may respond slowly or be temporarily unavailable. GeoOccitania retries a failed load and provides a control to start the load again. An Overpass response is a view of current OSM data, not a GeoOccitania database.
See also:
5. Forms and OSM tags
For every field, the administrator defines:
- the technical OSM key;
- the label displayed in the interface;
- an empty or pre-filled value;
- whether the field is visible;
- whether the value is editable;
- whether the value is required.
A marker must contain at least one valid OSM tag. Hidden, fixed and required tags are sent with the values stored in the configuration.
GeoOccitania does not impose a closed list of possible keys. The administrator is responsible for checking that every configured key is valid and appropriate for the relevant type of OSM object.
See also:
6. Sending an edit to OpenStreetMap
GeoOccitania uses OpenStreetMap OAuth 2. For each confirmed written contribution, the server:
- reads the current version of the object again;
- adds only the tags authorised by the selected marker;
- creates an OSM changeset;
- updates the OSM object;
- closes the changeset;
- stores an internal trace in GeoOccitania.
OpenStreetMap records the OSM contributor, the changeset and the tag history. GeoOccitania review is retrospective: the written edit is sent without waiting for approval from a verifier.
Contributors must check the object, keys and values before submission. Another mapper may modify an object between loading and submission; OSM can then reject the update because of a version conflict. The contributor must reload the object before trying again.
The Open Database License applies to OpenStreetMap data. The public OSM history is governed by OpenStreetMap's own policies.
See also:
7. Audio pronunciations
A contributor may:
- record a pronunciation with the device microphone;
- upload a file in an accepted audio format;
- listen to the prepared recording before sending it;
- send the audio independently of a written OSM contribution.
Three beeps announce the beginning of recording. The interface also suggests smiling before speaking to obtain a more natural voice.
Explicit consent is required. The Occitan consent statement means: “I have read and agree to the use and distribution of my recording under the CC BY 4.0 licence.”
A verifier may validate or delete an audio recording. Validated pronunciations can be played from the object's GeoOccitania record.
These files are not OSM data. OpenStreetMap does not store the recordings, consent records or audio-review decisions. They remain in GeoOccitania and are distributed under CC BY 4.0, separately from the ODbL-covered map data.
The speaker's identity or attribution, the consent date and the licence must be retained in the audio metadata. A contributor must record their own voice or have the speaker's clear consent.
Validated audio is not automatically sent to Wikimedia Commons. A future Commons workflow would require selection, suitable metadata and compliance with Commons policies.
See also:
8. Verification
The verification area is restricted to verifiers and administrators. It shows recent written contributions and audio-only records, with filters for themes and contributors.
For an OSM contribution, a verifier can inspect the public changeset and contact the contributor through OSM. For an audio record, a verifier can play, download, validate or delete the file. This process does not delay the initial written OSM edit.
9. Data stored by GeoOccitania
GeoOccitania maintains its own database for:
- theme, marker and form configuration;
- application roles;
- internal traces of written contributions;
- audio files and metadata;
- consent records;
- audio status and verifier actions;
- messages sent to the administrator;
- favourite themes.
OSM access tokens and session identifiers are secret session data. They must never appear in a wiki page, screenshot, public log, administrative export or repository.
10. Exports and backups
An administrator can:
- download contribution and audio metadata as CSV or JSON;
- export and restore the application configuration;
- download a database backup.
A database backup contains audio metadata but does not replace a copy of the audio objects. A complete backup strategy must include the database, the object-storage area, the configuration, copies held in a separate location and regular restoration tests.
Before public opening, the operators must define and test:
- recurring D1 database backups;
- separate R2 audio-object backups;
- encryption and restricted access for private copies;
- verified restoration of the relationship between database metadata and audio objects;
- a retention period for sessions, tokens, messages, contribution traces, audio, consent, moderation events, logs and backups.
11. Simplified architecture
Web browser ├─ GeoOccitania interface ├─ OSM / OSM-oc map tiles └─ Overpass queries GeoOccitania server ├─ OSM OAuth 2 authentication ├─ OSM contribution API ├─ configuration and roles ├─ verification and exports ├─ SQL metadata database └─ audio object storage External services ├─ OpenStreetMap API ├─ Overpass API └─ map tile services
The principal dependencies are OpenStreetMap for authentication and map edits, Overpass for selecting visible objects, OSM and OSM-oc tile services for map backgrounds, a SQL database for metadata and workflow, and object storage for audio.
12. Installation and deployment principles
Public documentation should describe only the general procedure:
- obtain the source in a protected workspace;
- install dependencies;
- create the database and apply migrations;
- create object storage for audio;
- register a public, non-confidential OAuth 2 application with OpenStreetMap;
- use the OAuth authorisation-code flow with PKCE;
- configure the authorised callback URL;
- define runtime values in the hosting provider's protected settings;
- build and verify the application;
- deploy a saved version;
- test sign-in, Overpass, an OSM edit, audio, verification, exports and restoration.
The OAuth client identifier and callback URL may be documented once they belong to the permanent deployment. The following must never be published:
- an OAuth client secret;
- OSM access tokens;
- session identifiers or cookies;
- API keys and database credentials;
- object-storage credentials or internal object keys;
- complete database backups;
- private messages or personal data;
- screenshots containing any of the above.
If a secret is disclosed, deleting the text is not sufficient: the secret must be revoked and replaced.
13. Security and responsibilities before public opening
The private V1 is not a declaration of production readiness. Before access is extended to visitors or the public, the operators must:
- revoke any credential disclosed during development;
- use a public OAuth client with PKCE and request only necessary scopes;
- validate the permanent callback addresses;
- establish per-account and per-IP rate limits for sign-in, Overpass loads, OSM submissions, audio uploads, messages, exports and backups;
- ensure that temporary blocking never deletes an already recorded contribution;
- complete and test D1 and R2 backup and restoration procedures;
- publish a data-retention and privacy policy;
- provide a contact and a process for requesting deletion of an audio file or an internal message;
- configure a permanent HTTPS domain and update the OAuth callback;
- test contributor, verifier and administrator permissions;
- test desktop, tablet and phone layouts;
- document the response to data loss, unauthorised access and failed OSM submissions.
Screenshots for the wiki must use prepared demonstration data. They must not show email addresses, private messages, exact personal locations, browser history, tokens, secrets, cookies, internal database identifiers or the real name of a contributor without consent.
14. Known limitations
- Overpass may be slow or unavailable, and broad queries may fail.
- The microphone and geolocation depend on browser permissions.
- Audio storage is separate from OpenStreetMap.
- The web V1 is not yet a native or installable application.
- OSM history and GeoOccitania's internal records are separate.
- Configuring a marker requires basic knowledge of Overpass QL and OSM tagging.
- The current V1 remains private while public-service security, backup, retention and domain prerequisites are completed.
15. Possible future work
- an illustrated contributor guide;
- short training material;
- presentation videos for social media;
- an installable or native application;
- a reviewed workflow for selected audio on Wikimedia Commons;
- possible links to Wikidata;
- automated backups and restoration tests;
- aggregate statistics that respect personal data.
16. Illustration plan
The numbered placeholders above use the same sequence as the illustration plan:
- Home menu and favourite themes.
- OSM-oc map with differently coloured markers.
- Marker cluster and zoom.
- Form with Occitan labels and OSM keys.
- Hidden tags in technical information.
- Confirmation before submission to OSM.
- Link to the public changeset.
- Audio recording and consent.
- Verification area.
- Theme and marker administration.
- Form-tag configuration and
{bbox}help. - Exports and database/audio backup.
Each published image must state the relevant role and what the user should check before continuing. Image credits and licences must be defined before upload.