# API ADS

{% hint style="success" %}
**Qu'est ce que l'API ADS du RNB ?**\
\
L'API ADS permet aux instructeurs des Droits du Sol d'ajouter des informations sur un bâtiment existant (ex : Démoli) ou de créer un nouveau bâtiment au sein du RNB.&#x20;

\
Une fois vos ADS ajoutées sur le RNB, l’ensemble de vos nouvelles informations bâtimentaires pourront ainsi être accessibles par tous les services de votre collectivité.
{% endhint %}

## Accès réservé

**L’API dédiée aux Autorisations du Droit des Sols (ADS) est réservée aux communes.**&#x20;

[Faire une demande d'accès ->](https://tally.so/r/nG1k82)

## Identification

Toutes les requêtes liées aux ADS doivent faire l’objet d’une authentification. Pour vous identifier, utilisez le token fourni par l’équipe du RNB. Pour faire une demande de token, [renseignez ce formulaire](https://tally.so/r/nG1k82).

**Ajoutez une clé `Authorization` aux headers HTTP de chacune de vos requêtes.** La valeur doit être votre token **préfixé** de la chaîne “Token”. Un espace sépare “Token” et votre token.

```
Authorization: Token 9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b
```

## Liste et recherche d'ADS

### Endpoint

```
GET https://rnb-api.beta.gouv.fr/api/alpha/ads/
```

### Filtres de recherche

Les filtres de recherche sont à transmettre sous forme de paramètres d’url.

{% code title="Exemple" %}
```
GET https://rnb-api.beta.gouv.fr/api/alpha/ads/?since=2023-01-01
```
{% endcode %}

**Détails des filtres disponibles**

<table data-full-width="true"><thead><tr><th width="138.5">Paramètre</th><th width="140">Format</th><th width="114">Défaut</th><th>Commentaire</th></tr></thead><tbody><tr><td>q</td><td>string</td><td>null</td><td>Recherche parmi les n° de dossiers (propriété <code>file_number</code>). Accepte les n° de dossier incomplets. Insensible à la casse.</td></tr><tr><td>since</td><td>AAA-MM-DD</td><td>null</td><td>Récupère tous les dossiers dont la propriété <code>decided_at</code> est supérieure ou égale à la valeur demandée.</td></tr></tbody></table>

### Exemple de réponse

{% code fullWidth="true" %}
```json
{
    "count": 3,
    "next": null,
    "previous": null,
    "results": [
        {
            "file_number": "TEST03818519U9999",
            "decided_at": "2023-06-01",
            "buildings_operations": [
                {
                    "rnb_id": "A1B2C3A1B2C3",
                    "shape": null,
                    "operation": "build"
                },
                {
                    "rnb_id": null,
                    "shape": {
                        "type": "Point",
                        "coordinates": [
                            5.722961565015281,
                            45.1851103238598
                        ]
                    }
                    "operation": "demolish"
                },
                {

                    "rnb_id": "1M2N3O1M2N3O",
                    "shape": {
                        "type": "Point",
                        "coordinates": [
                            5.723006573148693,
                            45.1851402293713
                        ]
                    },
                    "operation": "demolish"
                }
            ]
        },
        {
            "file_number": "PC3807123200WW",
            "decided_at": "2023-05-01",
            "buildings_operations": [
                {
                    "rnb_id": "FXFJZNZYGTED",
                    "shape": null
                    "operation": "build"
                }
            ]
        },
        {
            "file_number": "PC384712301337",
            "decided_at": "2023-02-22",
            "buildings_operations": [
                {
                    "rnb_id": "RXNOSN2DUCLG",
                    "geometry": {
                        "type": "Point",
                        "coordinates": [
                            5.775791408470412,
                            45.256939624268206
                        ]
                    }
                    "operation": "modify"
                }
            ]
        }, 
    ]
}
```
{% endcode %}

## Création et modification d'une ADS

### Endpoints

{% hint style="warning" %}
**NB :** n’oubliez pas le slash à la fin des endpoints
{% endhint %}

#### Endpoint de création

```
POST https://rnb-api.beta.gouv.fr/api/alpha/ads/
```

#### Endpoint de modification

```
PUT https://rnb-api.beta.gouv.fr/api/alpha/ads/[file_number]/
```

### Requête

Les requêtes de création et de modification sont identiques. Seuls l’URL des endpoints et la méthode HTTP diffèrent.

**Détails d'une requête**

<table data-full-width="true"><thead><tr><th width="223.66666666666663">Paramètre</th><th width="154">Format</th><th>Commentaire</th></tr></thead><tbody><tr><td>file_number</td><td>string</td><td>Requis. Doit être unique. N° de dossier de l’ADS. Au format “PC333802300001”.</td></tr><tr><td>decided_at</td><td>AAA-MM-DD</td><td>Requis. Date d’acceptation de l’ADS par l’instructeur.</td></tr><tr><td>buildings_operations</td><td>array</td><td>Requis. Liste des constructions, modifications et démolition de bâtiments liées à cette ADS. Voir tableau ci-dessous pour le détail d’un élément de cette liste.</td></tr></tbody></table>

**Détails des éléments contenus dans `buildings_operations` :**&#x20;

<table data-full-width="true"><thead><tr><th width="221.66666666666663">Paramètre</th><th width="160">Format</th><th>Commentaire</th></tr></thead><tbody><tr><td>operation</td><td>string parmi choix restreint</td><td><p></p><p>Requis. Valeurs possibles :</p><ul><li><code>build</code> (construction neuve)</li><li><code>modify</code> (modification d’un bâtiment existant)</li><li><code>demolish</code> (démolition complète)</li></ul></td></tr><tr><td>rnb_id</td><td>string</td><td><p>Optionnel. Doit être un ID-RNB existant dans le RNB.</p><p>ID-RNB du bâtiment (ex : ABCD1234WXYZ) → l’ADS concerne un bâtiment déjà présent dans le RNB</p></td></tr><tr><td>shape</td><td>géométrie geojson (SRID 4326)</td><td>Une géométrie représentant le bâtiment.</td></tr></tbody></table>

### Exemples

#### Exemple : création d’une ADS liée à un bâtiment présent dans le RNB

{% code fullWidth="true" %}
```json
//////////////////
// Requête
//////////////////
{
	"file_number": "PCXXXXXXXXXX",
	"decided_at": "2019-03-18",
	"buildings_operations": [
	    {
	        "operation": "demolish",
	        "rnb_id": "ABCD1234WXYZ", // Pour un bâtiment connu du RNB, indiquez son rnb_id
	    }
	],
}

//////////////////
// Réponse
//////////////////
{
	"file_number": "PCXXXXXXXXXX",
	"decided_at": "2019-03-18",
	"buildings_operations": [
	    {
	        "operation": "build",
	        "rnb_id": "ABCD1234WXYZ",
	    	"shape": null
	    }
	],
}
```
{% endcode %}

#### Exemple : création d’une ADS liée à deux bâtiments dont on ne connait pas l'identifiant RNB

{% code fullWidth="true" %}
```json
//////////////////
// Requête
//////////////////
{
	"file_number": "PCXXXXXXXXXX",
	"decided_at": "2019-03-18",
	"buildings_operations": [
	    {
	        "operation": "build",
	        "shape": {
	            "type": "Point",
	            "coordinates": [2.3552747458487002, 48.86958288638419],
	        }
	    },
	    {
	        "operation": "build",
                "shape": {
                    "type": "Point",
                    "coordinates": [2.3547872809558203, 48.86945119575674],
                },
	    },
	],
}

//////////////////
// Réponse
//////////////////
{
	"file_number": "PCXXXXXXXXXX",
	"decided_at": "2019-03-18",
	"buildings_operations": [
	    {
	        "operation": "build",
                "rnb_id": null,
                "shape": {
                    "type": "Point",
                    "coordinates": [2.3552747458487002, 48.86958288638419],
                }
	    },
	    {
	        "operation": "build",
	        "rnb_id": null,
	        "shape": {
	            "type": "Point",
	            "coordinates": [2.3547872809558203, 48.86945119575674],
	         },	 
	    },
	],
}
```
{% endcode %}

#### Exemple : création d’une ADS concernant la démolition d’un bâtiment connu du RNB et la construction d’un nouveau bâtiment absent du RNB

{% code fullWidth="true" %}
```json
//////////////////
// Requête
//////////////////
{
	"file_number": "PCXXXXXXXXXX",
	"decided_at": "2019-03-10",
	"buildings_operations": [
	    {
	        "operation": "demolish",
	        "rnb_id": "7865HG43PLS9", // Destruction du bâtiment existant, déjà connu par le RNB
	    },
	    {
	        "operation": "build",
                "shape": {
                    "type": "Point",
                    "coordinates": [2.3552747458487002, 48.86958288638419],
                },
	    }
	],
}

//////////////////
// Réponse
//////////////////
{
	"file_number": "PCXXXXXXXXXX",
	"decided_at": "2019-03-10",
	"buildings_operations": [
	    {
	        "operation": "demolish",
	        "rnb_id": "7865HG43PLS9", 
	        "shape": null
	    },
	    {
	        "operation": "build",
	        "rnb_id": null, 
                "shape": {
                    "type": "Point",
                    "coordinates": [2.3552747458487002, 48.86958288638419],
                },
	    }
	],
}
```
{% endcode %}

## Suppression d’une ADS

### Endpoint

```
DELETE https://rnb-api.beta.gouv.fr/api/alpha/ads/[file_number]/
```

