{"id":13930113,"url":"https://github.com/AgenceBio/cartobio-api","last_synced_at":"2025-07-19T12:31:30.113Z","repository":{"id":40796047,"uuid":"180534648","full_name":"AgenceBio/cartobio-api","owner":"AgenceBio","description":"CartoBio API","archived":false,"fork":false,"pushed_at":"2024-10-29T10:59:01.000Z","size":3461,"stargazers_count":5,"open_issues_count":6,"forks_count":2,"subscribers_count":6,"default_branch":"main","last_synced_at":"2024-10-29T11:57:39.521Z","etag":null,"topics":["agriculture-data","cartobio","eig-2019","entrepreneur-interet-general","geographical-information-system","organic-agriculture","postgis","postgresql"],"latest_commit_sha":null,"homepage":"https://cartobio.agencebio.org","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AgenceBio.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-04-10T08:14:31.000Z","updated_at":"2024-10-09T08:46:41.000Z","dependencies_parsed_at":"2023-12-29T11:29:24.787Z","dependency_job_id":"e27a1a53-d884-412c-b4ab-ee3fcbaf422d","html_url":"https://github.com/AgenceBio/cartobio-api","commit_stats":{"total_commits":496,"total_committers":6,"mean_commits":82.66666666666667,"dds":"0.38306451612903225","last_synced_commit":"e2376747d5283c65644e7d062dbb67802554916e"},"previous_names":[],"tags_count":138,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AgenceBio%2Fcartobio-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AgenceBio%2Fcartobio-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AgenceBio%2Fcartobio-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AgenceBio%2Fcartobio-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AgenceBio","download_url":"https://codeload.github.com/AgenceBio/cartobio-api/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":226607591,"owners_count":17658481,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agriculture-data","cartobio","eig-2019","entrepreneur-interet-general","geographical-information-system","organic-agriculture","postgis","postgresql"],"created_at":"2024-08-07T18:04:46.536Z","updated_at":"2025-07-19T12:31:30.108Z","avatar_url":"https://github.com/AgenceBio.png","language":"JavaScript","funding_links":[],"categories":["postgresql"],"sub_categories":[],"readme":"# CartoBio - API\n\n\u003e API des données parcellaires bio en France.\n\nElle est utilisée par [`cartobio-front`](https://github.com/agencebio/cartobio-front) et aux outils\nmétiers des organismes de certification du bio en France.\n\nCette API est réalisée en node avec [Fastify](https://fastify.dev/) et [swagger-ui](https://swagger.io/tools/swagger-ui/) entre autres et la base de données maintenue avec [db-migrate-pg](https://github.com/db-migrate/pg). Les données sont stockées dans une base [PostgreSQL](https://www.postgresql.org/) avec la cartouche spatiale [PostGIS](https://postgis.net/).\n\nLes erreurs sont centralisées avec [Sentry](https://github.com/getsentry/sentry).\n\n## Développement\n\n### Outils nécessaires\n\n-   `docker` avec `compose 2`\n-   `node` 20\n\nOn pourra utiliser `nvm` pour faciliter la gestion de différentes versions de node (cf. [`.nvmrc`](.nvmrc)) :\n\n```sh\nnvm install \u0026\u0026 nvm use\n```\n\n### Configuration\n\nCréer un fichier `.env` inspiré de `.example.env`.\n\n### Dépendances\n\nDémarrer le serveur de données :\n\n```sh\ndocker compose up db --force-recreate\n```\n\n### Application\n\nRécupérer les dépendances :\n\n```sh\n# Versions verrouillées\nnpm ci\n\n# Et/ou en les mettant à jour\nnpm install\n```\n\nDémarrer :\n\n```sh\nnpm start\n\n# Ou en rechargeant automatiquement\nnpm run watch\n```\n\nOuvrir :\n\n-   http://localhost:8000/api/version\n-   http://localhost:8000/api/v2/test\n-   http://localhost:8000/api/documentation/static/index.html\n\n💡 Le démarrage du serveur lance automatiquement les migrations du schéma de base de données avec [**db-migrate**](https://db-migrate.readthedocs.io/en/latest/). Se réferrer à sa documentation pour en savoir plus sur les commandes et les API de migration.\n\n### Données de tests dans la base\n\n```sh\n# Ajouter\n./node_modules/.bin/db-migrate up\n\n# Retirer\n./node_modules/.bin/db-migrate down\n```\n\n### Exécution des tests\n\nLes test utilisent [Jest](https://jestjs.io/docs/en/getting-started) et [supertest](https://github.com/visionmedia/supertest#readme) pour leur organisation et pour lancer les appels HTTP.\n\n```sh\nnpm test\n```\n\n## Déploiement\n\n### Environnement de test\n\n### Environnement de préproduction et production\n\nLe workflow [Docker Image CI](https://github.com/AgenceBio/cartobio-api/blob/main/.github/workflows/docker.yml) dispose de trois jobs :\n\n-   `build`\n    -   construit les images docker [agencebio/cartobio-api](https://hub.docker.com/r/agencebio/cartobio-api/tags)\n-   `deploy-staging`\n    -   déclenché par un nouveau commit dans la branche `main`\n    -   déploie l'API de préproduction\n-   `deploy-production`\n    -   déclenché par un nouvrau tag\n    -   déploie l'API de production\n\nPour créer un tag :\n\n```sh\n# Lors d'ajout de fonctionnalités\nnpm version minor\n\n# Lors d'un correctif ou ajout très mineur\nnpm version patch\n```\n\nPuis :\n\n```sh\ngit push --tags\n```\n\n---\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eAutres informations\u003c/b\u003e\u003c/summary\u003e\n\n# TODO : reprendre\n\n## Fonctionnement\n\n### Routes\n\n| Verbe   | Chemin                         | Description                                                                               |\n| ------- | ------------------------------ | ----------------------------------------------------------------------------------------- |\n| `GET`   | `/api/v1/version`              | Affiche la version de l'API.                                                              |\n| `POST`  | `/api/v1/test`                 | Teste le jeton d'authentification.                                                        |\n| `POST`  | `/api/v1/login`                | S'authentifie auprès du portail Notification de l'Agence Bio — et de l'API CartoBio.      |\n| `GET`   | `/api/v1/pacage/:numeroPacage` | Vérification de l'existence d'un PACAGE                                                   |\n| `PATCH` | `/api/v1/operator/:numeroBio`  | Mise à jour partielle des données opérateur (numéro pacage présent/absent, etc.)          |\n| `GET`   | `/api/v1/summary`              | Liste géolocalisée (précision : département) des clients d'un Organisme de Certification. |\n| `GET`   | `/api/v1/parcels`              | Liste des parcelles des clients d'un Organisme de Certification.                          |\n| `GET`   | `/api/v1/parcels/operator/:id` | Liste des parcelles d'un opérateur donné.                                                 |\n\nL'authentification est assurée grâce à des [jetons JWT](https://jwt.io/), issus à la main.\n\n### Variables d'environnement\n\nL'application lit les variables définies dans un fichier `.env`.\n\n| Variable                    | Défault                                      | Description                                                                                               |\n| --------------------------- | -------------------------------------------- | --------------------------------------------------------------------------------------------------------- |\n| `PORT`                      | `8000`                                       | Port réseau sur lequel exposer l'application                                                              |\n| `HOST`                      | `localhost`                                  | Interface réseau sur laquelle exposer l'application                                                       |\n| `DATABASE_URL`              | `http://docker:docker@api-db:15432/cartobio` | URL de la base de données PostGIS qui contient les couches géographiques, et les données métiers CartoBio |\n| `SENTRY_DSN`                | ``                                           | DSN Sentry pour le suivi des erreurs applicatives                                                         |\n| `CARTOBIO_JWT_SECRET`       | ``                                           | Secret JSON Web Token, pour vérifier l'authenticité des tokens                                            |\n| `NOTIFICATIONS_AB_ENDPOINT` | `https://back.agencebio.org`                 | Point d'accès aux [notifications de l'Agence Bio](https://preprod-notification.agencebio.org/)            |\n\n## Brancher au Webservice des Douanes\n\nEn local, il est impossible d'accéder au webservice des Douanes en direct. Il convient alors d'utiliser un proxy SOCKS via le serveur CartoBio :\n\n```sh\nssh -A -N -C -D 5000 -J user@ip-serveur-cartobio user@ip-serveur-bdd\n```\n\n## Sauvegarder et restaurer la base de données en production\n\n```sh\ndocker run --rm postgres:15 pg_dump --clean -t cartobio_operators -t cartobio_parcelles --data-only -U postgres -h bdd-cartobio -p 5433 postgres \u003e dump-production-data-only.sql\n```\n\nPuis restaurer (en préprod) :\n\n```sh\ndocker run -i --rm postgres:15 psql -v ON_ERROR_STOP=1 -U postgres -h bdd-cartobio -p 5434 postgres \u003c dump-production-data-only.sql\n```\n\n**Remarque** : `bdd-cartobio` est un alias de `162.19.57.177` ; le port `5433` correspond à la base de production, et `5434` à la base de préprod.\n\n## Intégration des données du RPG bio\n\nCes données sont utilisées pour la fonctionnalité d'import en un clic.\nElles sont basées sur le [dump statique](#générer-les-fonds-de-carte) utilisé pour le fond de carte.\n\n```sh\nogr2ogr -f PostgreSQL \\\n  PG:'postgresql://postgres@bdd-cartobio:5433/postgres' rpg.gpkg \\\n  -preserve_fid -nln rpg_bio -nlt POLYGON \\\n  --config PG_USE_COPY YES --config OGR_TRUNCATE YES\n```\n\n## Intégration des données des départements avec le demaine maritime\n\nCes données sont utilisées lors du déclencheur (`update_communes`) d'ajout de commune à une parcelle afin de trouver la commune la plus proche pour les parcelles aquacoles et de marquer les parcelles frontalières comme `etranger`.\nElles sont basées sur les géométries des [régions](https://etalab-datasets.geo.data.gouv.fr/contours-administratifs/latest/geojson/) modifiées via QGIS pour rajouter le domaine maritimes francais.\n\n```sh\nogr2ogr -f PostgreSQL \\\n  PG:'postgresql://postgres@bdd-cartobio:5433/postgres' territoires.gpkg \\\n  -preserve_fid -nln territoires -nlt POLYGON \\\n  --config PG_USE_COPY YES --config OGR_TRUNCATE YES\n```\n\n## Générer les fonds de carte\n\n**Remarque** : Les fonds de carte étaient auparavant servis avec le logiciel Geoserver.\n\nLes fonds de carte sont servis statiquement, et générés à l'aide de l'outil en ligne de commande [tippecanoe] :\n\n```sh\n# Décompresser tous les fichiers ZIP départementaux dans un même dossier,\n# de telle sorte à ce que tous les fichiers .dbf .prj .shp .shx soient dans un même dossier.\nfor f in *.zip; do unzip \"$f\"; done\n\n# Convertir les données en GeoJSON, puis en MBTiles.\nogr2ogr -t_srs EPSG:3857 -nln rpg rpg.gpkg .\nogr2ogr rpg.geojson rpg.gpkg\ntippecanoe -Z10 -z14 --extend-zooms-if-still-dropping --no-tile-compression --simplify-only-low-zooms --drop-densest-as-needed --output-to-directory rpg-202x --projection EPSG:3857 --name \"RPG 202x\" --layer \"rpg202x\" --exclude NUM_ILOT --exclude NUM_PARCEL --exclude PACAGE --force rpg.geojson\n```\n\n## Autodétéction des communes\n\nLes communes sont ajoutées automatiquement pour un déclencheur en BDD\n\nVia la fonction :\n\n```sql\nupdate_communes()\n```\n\nDéclenchée par :\n\n```sql\nBEFORE INSERT OR UPDATE ON cartobio_parcelles\n```\n\n## Cron\n\nPour lister les cron:\n\n```sh\ncrontab -l\n```\n\nPour mettre à jour:\n\n```sh\ncrontab -e\n```\n\nTous les mois les parcellaires marqués comme supprimés (`deleted_at`) depuis plus de 6 mois, sont supprimés dans la base de données.\n\nLe script supprimant les parcellaires est utilisable via `npm run clean-records`\n\nExemple d'utilisation dans le crontab:\n\n```sh\n* 1 * * * (date \u0026\u0026 docker exec cartobio-api-test npm run clean-records) \u003e\u003e /var/log/cron.log\n```\n\n\u003c/details\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FAgenceBio%2Fcartobio-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FAgenceBio%2Fcartobio-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FAgenceBio%2Fcartobio-api/lists"}