====== API REST sur BANADORA ======

À l'URL https://web-services-arar.mom.fr/api-banadora/ est accessible une API REST pour consulter les résultats de datation présents dans la base BANADORA, consultable aussi sur https://banadora.mom.fr.

Cette API permet d'accéder à une vue //v_results// regroupant l’essentiel des informations sur un échantillons et les résultats de datation associés.

===== Informations disponibles =====

^ nom du champs/attribut ^ désignation ^
| publication_laboratory_reference | référence unique de la datation C14 |
| num_entree                       | UID de l’ancienne base (DBF) |
| sample_name                      | nom de l’échantillon |
| sampling_date                    | date d’échantillonnage |
| archaeological_layer             | réf. de la couche archéologique |
| was_analysed_by_ams              | analysé par AMS |
| was_analysed_in_artemis_program  | analysé via le projet AMS Artemis |
| reception_date                   | date de réception au C14 |
| sample_nature                    | nature/type d’échantillon |
| sample_deposit_mode              | mode de gisement |
| sampling_mode                    | mode de prélèvement |
| discipline                       | discipline : archéo ou géologie |
| result_signe                     | signe de l’âge C14 |
| result_age14c_bp                 | C14 âge BP |
| result_uncertainty               | incertitude |
| result_counting_year             | année de comptage |
| result_activity                  | activité |
| result_error_activity            | erreur activité |
| result_age_position              | période archéologique |
| result_age1                      | |
| result_age2                      | |
| archaeological_period            | période archéologique |
| arch_reliability                 | fiabilité de la datation |
| country_iso3166                  | code ISO 3166 du pays |
| location_department              | nom du département |
| location_department_code         | code du département |
| site_name                        | nom du site |
| town_name                        | nom de la commune/ville |
| latitude						   | GPS latitude (WGS84) |
| longitude						   | GPS longitude (WGS84) |
| banadora_web_site_result_url	   | URL de la page du résultat correspondant sur le site principal banadora.mom.fr, permettant ainsi de référencer/citer l'origine de l'information, et aussi d'obtenir quelques informations complémentaire (archéologue/géologue à l'origine de la demande…) |

les retours sont triés (ORDER BY) sur le nom de l'échantillon (sample_name)

===== Utilisation =====

<note tip>Cette API REST est basée sur PostgREST, les opérateurs et filtres utilisables peuvent être consulté sur l'aide officielle : https://postgrest.org/en/stable/references/api/tables_views.html#operators</note>

<note tip>Pour faire vos essais, vous pouvez bien sûr les faire avec votre navigateur web ou en ligne de commande (curl) ou avec un logiciel comme [[https://www.usebruno.com/|Bruno]]</note>

Pour commencer, vous pouvez simplement lancer une requête simple du type :\\
([[https://web-services-arar.mom.fr/api-banadora/v_results?limit=3]])
<code bash>
https://web-services-arar.mom.fr/api-banadora/v_results?limit=3
# le limit=3 permet de ne retourner que 3 résultats (en son absence, au plus 100 résultats seront retournés)
# la requête suivante retournera 3 résultats en évitant des champs //null// ou vides :
https://web-services-arar.mom.fr/api-banadora/v_results?and=(result_age14c_bp.not.eq.0,sampling_mode.not.is.null,sample_name.not.eq."",arch_reliability.not.is.null,archaeological_period.not.is.null,latitude.not.is.null)&limit=3
</code>

À partir des champs disponibles et des opérateurs et filtres disponibles avec PostgREST, on peut par exemple demander les datations associés à un site. Pour l'exemple, nous demandons les noms des sites contenant //RONZ// (la base étant en PostgreSQL, la casse MAJUSCULES/minuscules est par défaut respecté, pour sans affranchir, utiliser //ilike// au lieu de //like// : 
<code bash>
https://web-services-arar.mom.fr/api-banadora/v_results?site_name=ilike.*ronz*&limit=20
# si on veut en plus exclure l'absence de datations et que le mode de prélèvement soit bien renseigné, cela donne :
https://web-services-arar.mom.fr/api-banadora/v_results?and=(result_age14c_bp.not.eq.0,sampling_mode.not.is.null,site_name.like.*RONZ*)&limit=20
</code>

On peut aussi ajouter des critères sur le champs numérique et booléen, par exemple pour récupérer 30 résultats de datation réalisées par AMS en 2024 ou plus récemment, on peut exécuter :
<code bash>
https://web-services-arar.mom.fr/api-banadora/v_results?and=(result_age14c_bp.not.eq.0,was_analysed_by_ams.eq.true,sampling_date.gte.2024)&limit=30
</code>