addresses cleanup

Author: parmentelat

notebooks/geo-tps/addresses/.teacher/README-addresses-corrige-nb.md

@@ -9,8 +9,8 @@ kernelspec:
   name: python3
 language_info:
   name: python
-  nbconvert_exporter: python
   pygments_lexer: ipython3
+  nbconvert_exporter: python
 ---
 
 # TP géoloc addresses
@@ -62,14 +62,19 @@ on va utiliser principalement
 
 +++
 
-## géolocalisation
+## l'API de géolocalisation
 
 pour obtenir des coordonnées latitude/longitude à partir d'une adresse, en France on peut utiliser un service public et gratuit ici  
 **<https://adresse.data.gouv.fr/api-doc/adresse>**  
-lisez bien cette page, et notamment tout en bas il y a une zone où vous pouvez faire une recherche en ligne
+
+```{admonition} la doc a disparu !
+dans une version antérieure, cette URL donnait le mode d'emploi de l'API de géolocalisation  
+mais ! en Octobre 2025, la documentation semble en pleine refonte,  
+et si l'URL existe toujours, **elle ne contient plus cette information**...
+```
 
 ```{code-cell} ipython3
-# for starters, we only need the 'regular fit' pandas
+# for starters, we only need the 'regular fit' - i.e. non geo - pandas
 
 import pandas as pd
 ```
@@ -86,6 +91,10 @@ addresses.head(4)
 
 et la première chose qu'on va faire, c'est naturellement d'utiliser cette API pour géolocaliser ces adresses
 
++++
+
+### un petit extrait
+
 mais avant cela, je vous recommande de produire un fichier `addresses-small.csv` qui contient un petit extrait, disons les 10 ou 20 premières lignes; ce sera très utile pour débugger
 
 ```{code-cell} ipython3
@@ -114,13 +123,13 @@ c'est très pratique de pouvoir faire une recherche des adresses 'une par une';
   `https://api-adresse.data.gouv.fr/search/?q=3+rue+tourelles,Paris`
 - observez le format de ce que vous recevez, qu'est-ce que ça peut être ?
 - ajoutez `&limit=1` à l'url pour que cela donne  
-  `https://api-adresse.data.gouv.fr/search/?q=3+rue+tourelles,Paris&limit=1`
-  quelle est la différence ?
+  `https://api-adresse.data.gouv.fr/search/?q=3+rue+tourelles,Paris&limit=1`  
+  quelle différence observez-vous dans le résultat ?
 
 +++
 
 ````{admonition} ? et & dans l'URL
-:class: note
+:class: note dropdown
 
 ici lorsqu'on envoie donc une requête vers l'URL  
 `https://api-adresse.data.gouv.fr/search/?q=18+rue+BERNARDINS,Paris&limit=1`  
@@ -159,7 +168,7 @@ et notamment vous devriez tomber sur une page qui commence avec cet exemple
 {'private_gists': 419, 'total_private_repos': 77, ...}
 ```
 
-qui devrait vous inspirer pour l'écriture de la fonction suivante
+qui devrait vous éclairer sur l'usage de base de la librairie
 
 ```{code-cell} ipython3
 # requests is the swiss knife for doing http
@@ -168,20 +177,22 @@ import requests
 ```
 
 ```{code-cell} ipython3
-# here's how to use the API
+# to localize ONE address
+# we just need to forge the right URL
 
 def localize_one(num, typ, nom):
 
     # we build the URL which directly contains the address pieces
     url = f"https://api-adresse.data.gouv.fr/search/?q={num}+{typ}+{nom},Paris&limit=1"
+    
     # print(f"localize_one is fetching page\n{url}")
 
     # sending request to the web server
     response = requests.get(url)
 
     # if all is OK, http returns a code in the [200 .. 300[ range
     if not (200 <= response.status_code < 300):
-        print("WHOOPS....")
+        print(f"WHOOPS.... {response.status_code=}")
         return
 
     # we can then read the answer 
@@ -238,26 +249,6 @@ details = localize_one(18, 'rue', 'BERNARDINS')
 30_000 * .100
 ```
 
-````{admonition} ? et & dans l'URL
-:class: note dropdown
-
-dans une autre dimension complètement: ici on envoie donc une requête vers l'URL  
-`https://api-adresse.data.gouv.fr/search/?q=18+rue+BERNARDINS,Paris&limit=1`
-
-Les caractères `?` et `&` jouent un rôle particulier: pour information, la syntaxe générale c'est
-```
-http://le.host.name/le/path?param1=truc&param2=bidule&param3=machinechose
-```
-
-et donc de cette façon, c'est un peu comme si on appelait une fonction à distance, en lui passant
-- `q=18+rue+BERNARDINS,Paris` (`q` pour *query*)
-- et `limit=1` (pour avoir seulement la première réponse)
-
-et pour vous faire réfléchir: il se passerait quoi si par exemple dans la colonne `name` il y avait un caractère `&` (imaginez la rue *Bouvart & Ratinet*)
-````
-
-+++
-
 ### en un seul coup
 
 si vous avez bien lu la page qui décrit l'API, vous devez avoir remarqué qu'il y a une autre façon de lui soumettre une recherche  
@@ -393,15 +384,15 @@ def mass_post(filename, col_number, col_type, col_name, col_city):
 def localize_many(filename, col_number, col_type, col_name, col_city):
     df = pd.read_csv(filename)
     geoloc = mass_post(filename, col_number, col_type, col_name, col_city)
-    # because we don't set an index, it it safe to merge
+    # because we don't set an index, it is safe to merge
     geoloc = geoloc[['latitude', 'longitude', 'result_city', 'result_type']]
     return df.merge(geoloc, left_index=True, right_index=True)
 ```
 
 ```{code-cell} ipython3
 :tags: [level_basic]
 
-# try your code on the small sample for starters
+# try this code on the small sample for starters
 
 addresses_small = localize_many("data/addresses-small.csv", "number", "type", "name", "city")
 addresses_small
@@ -423,14 +414,16 @@ addresses_small
 
 # prune-cell
 
-# sanity check
+# sanity check - should return True, True
 
 addresses_small = localize_many("data/addresses-small.csv", "number", "type", "name", "city")
 
-
-( sum(addresses_small.result_city != 'Paris') == 0
- and
-  sum(addresses_small.result_type != 'housenumber') == 0)
+(
+    # are all addresses in Paris
+    all(addresses_small.result_city == 'Paris'),
+    # are all addresses for a house - as opposed to a street or worse
+    all(addresses_small.result_type == 'housenumber'),
+)
 ```
 
 ```{code-cell} ipython3

notebooks/geo-tps/addresses/README-addresses-nb.md

@@ -9,8 +9,8 @@ kernelspec:
   name: python3
 language_info:
   name: python
-  nbconvert_exporter: python
   pygments_lexer: ipython3
+  nbconvert_exporter: python
 ---
 
 # TP géoloc addresses
@@ -62,14 +62,19 @@ on va utiliser principalement
 
 +++
 
-## géolocalisation
+## l'API de géolocalisation
 
 pour obtenir des coordonnées latitude/longitude à partir d'une adresse, en France on peut utiliser un service public et gratuit ici  
 **<https://adresse.data.gouv.fr/api-doc/adresse>**  
-lisez bien cette page, et notamment tout en bas il y a une zone où vous pouvez faire une recherche en ligne
+
+```{admonition} la doc a disparu !
+dans une version antérieure, cette URL donnait le mode d'emploi de l'API de géolocalisation  
+mais ! en Octobre 2025, la documentation semble en pleine refonte,  
+et si l'URL existe toujours, **elle ne contient plus cette information**...
+```
 
 ```{code-cell} ipython3
-# for starters, we only need the 'regular fit' pandas
+# for starters, we only need the 'regular fit' - i.e. non geo - pandas
 
 import pandas as pd
 ```
@@ -86,6 +91,10 @@ addresses.head(4)
 
 et la première chose qu'on va faire, c'est naturellement d'utiliser cette API pour géolocaliser ces adresses
 
++++
+
+### un petit extrait
+
 mais avant cela, je vous recommande de produire un fichier `addresses-small.csv` qui contient un petit extrait, disons les 10 ou 20 premières lignes; ce sera très utile pour débugger
 
 ```{code-cell} ipython3
@@ -106,13 +115,13 @@ c'est très pratique de pouvoir faire une recherche des adresses 'une par une';
   `https://api-adresse.data.gouv.fr/search/?q=3+rue+tourelles,Paris`
 - observez le format de ce que vous recevez, qu'est-ce que ça peut être ?
 - ajoutez `&limit=1` à l'url pour que cela donne  
-  `https://api-adresse.data.gouv.fr/search/?q=3+rue+tourelles,Paris&limit=1`
-  quelle est la différence ?
+  `https://api-adresse.data.gouv.fr/search/?q=3+rue+tourelles,Paris&limit=1`  
+  quelle différence observez-vous dans le résultat ?
 
 +++
 
 ````{admonition} ? et & dans l'URL
-:class: note
+:class: note dropdown
 
 ici lorsqu'on envoie donc une requête vers l'URL  
 `https://api-adresse.data.gouv.fr/search/?q=18+rue+BERNARDINS,Paris&limit=1`  
@@ -151,7 +160,7 @@ et notamment vous devriez tomber sur une page qui commence avec cet exemple
 {'private_gists': 419, 'total_private_repos': 77, ...}
 ```
 
-qui devrait vous inspirer pour l'écriture de la fonction suivante
+qui devrait vous éclairer sur l'usage de base de la librairie
 
 ```{code-cell} ipython3
 # requests is the swiss knife for doing http
@@ -160,20 +169,22 @@ import requests
 ```
 
 ```{code-cell} ipython3
-# here's how to use the API
+# to localize ONE address
+# we just need to forge the right URL
 
 def localize_one(num, typ, nom):
 
     # we build the URL which directly contains the address pieces
     url = f"https://api-adresse.data.gouv.fr/search/?q={num}+{typ}+{nom},Paris&limit=1"
+    
     # print(f"localize_one is fetching page\n{url}")
 
     # sending request to the web server
     response = requests.get(url)
 
     # if all is OK, http returns a code in the [200 .. 300[ range
     if not (200 <= response.status_code < 300):
-        print("WHOOPS....")
+        print(f"WHOOPS.... {response.status_code=}")
         return
 
     # we can then read the answer 
@@ -211,26 +222,6 @@ localize_one(18, 'rue', 'BERNARDINS')
 # your code here
 ```
 
-````{admonition} ? et & dans l'URL
-:class: note dropdown
-
-dans une autre dimension complètement: ici on envoie donc une requête vers l'URL  
-`https://api-adresse.data.gouv.fr/search/?q=18+rue+BERNARDINS,Paris&limit=1`
-
-Les caractères `?` et `&` jouent un rôle particulier: pour information, la syntaxe générale c'est
-```
-http://le.host.name/le/path?param1=truc&param2=bidule&param3=machinechose
-```
-
-et donc de cette façon, c'est un peu comme si on appelait une fonction à distance, en lui passant
-- `q=18+rue+BERNARDINS,Paris` (`q` pour *query*)
-- et `limit=1` (pour avoir seulement la première réponse)
-
-et pour vous faire réfléchir: il se passerait quoi si par exemple dans la colonne `name` il y avait un caractère `&` (imaginez la rue *Bouvart & Ratinet*)
-````
-
-+++
-
 ### en un seul coup
 
 si vous avez bien lu la page qui décrit l'API, vous devez avoir remarqué qu'il y a une autre façon de lui soumettre une recherche  
@@ -366,15 +357,15 @@ def mass_post(filename, col_number, col_type, col_name, col_city):
 def localize_many(filename, col_number, col_type, col_name, col_city):
     df = pd.read_csv(filename)
     geoloc = mass_post(filename, col_number, col_type, col_name, col_city)
-    # because we don't set an index, it it safe to merge
+    # because we don't set an index, it is safe to merge
     geoloc = geoloc[['latitude', 'longitude', 'result_city', 'result_type']]
     return df.merge(geoloc, left_index=True, right_index=True)
 ```
 
 ```{code-cell} ipython3
 :tags: [level_basic]
 
-# try your code on the small sample for starters
+# try this code on the small sample for starters
 
 addresses_small = localize_many("data/addresses-small.csv", "number", "type", "name", "city")
 addresses_small