one scotland gazetteer
1.0.0
Ce référentiel comprend deux choses :
(A) Code Python 3.x, exemples et scripts pour tester les services Web One Scotland Gazetteer (OSG) et le téléchargement FTP.
(B) Documentation générale pour les services Web OSG et FTP.
(A) Vous avez installé python 3.x dans votre système d'exploitation (OS)
(B) Vous êtes inscrit auprès du One Scotland Gazetteer (OSG) et pouvez-vous être autorisé à utiliser le service Web OSG ou le FTP OSG. Pour en savoir plus, veuillez visiter le site Web One Scotland Gazetteer.
(A) Modifiez le development.ini :
Dans le dossier racine de ce référentiel, modifiez le fichier development.ini et ajoutez votre nom d'utilisateur et votre mot de passe pour le FTP OSG et les services Web OSG. Ces informations d'identification sont fournies par le dépositaire du One Scotland Gazetteer et vous pouvez en avoir des différentes pour les services FTP et Web.
(B) Utilisez les exemples de services Web :
python rest.py
(C) Utilisez la fonctionnalité FTP en exécutant la commande suivante
python download_osg_using_ftp.py
Présentation : Cette documentation fournit des informations sur la manière d'utiliser par programmation deux des services "One Scotland Gazetteer" (OSG) :
(1) Services Web ; Le service web communique directement avec la base de données OSG et vous permet d'accéder au répertoire géographique en temps réel, en fournissant les informations les plus récentes. OSG prend en charge deux types de services : le "Representational state transfer" (REST) et le "Simple Object Access Protocol" (SOAP).
(2) Exporter des fichiers ; Une exportation peut être fournie au format Scottish Data Transfer Format (SDTF) sous forme de fichier CSV. Les exportations seront programmées à une fréquence prédéterminée. Un sous-ensemble de données peut également être fourni pour répondre à vos besoins.
Pour plus d’informations, veuillez visiter le site Web One Scotland Gazetteer.
Les services Web OSG sont structurés autour d'ensembles de données , qui contiennent des champs qui contiennent à leur tour les données réelles. Chaque ensemble de données de service Web renvoie différents champs et données et peut également prendre en charge différentes fonctionnalités. L'OSG dispose de deux services Web sendNGListDataSetsMessage (désormais list ) qui renvoie les ensembles de données disponibles pour les requêtes, et sendNGSearchMessage (désormais search ) qui permet d'effectuer des requêtes sur ces ensembles de données. Le nombre maximum d'enregistrements renvoyés par les services Web OSG ne peut pas dépasser 250 . Les descriptions des services OSG peuvent être trouvées respectivement sur REST et SOAP.
Authentification : tous les services Web OSG nécessitent une authentification à l'aide d'un username et d'un password . Un username et un password doivent être fournis dans les HTTP request headers pour chaque requête envoyée au service Web. Un exemple d'en-têtes de demande d'authentification pour REST et SOAP utilisant de fausses informations d'identification est disponible ci-dessous :
REPOS
Content-Type:application/json
Accept:application/json
username:Alice
password:secret
SAVON
<soapenv:Header>
<v0:HeaderLogin>
<username>Alice</username>
<password>secret</password>
</v0:HeaderLogin>
</soapenv:Header>
Autorisation : l'authentification auprès du service Web OSG à l'aide de votre username et password ne signifie pas que vous avez accès à tous les ensembles de données OSG disponibles. L'accès aux ensembles de données est géré par le dépositaire de l'OSG et si l'accès est nécessaire pour des ensembles de données supplémentaires, les utilisateurs doivent visiter le site Web One Scotland Gazetteer et formuler une demande. Par exemple, un utilisateur authentifié avec succès peut être autorisé à accéder au service Web de recherche ( sendNGSearchMessage ) uniquement avec l'ensemble de données EST_STANDARD_SEARCH mais pas avec l'ensemble de données ADDRESS_SEARCH .
Ensembles de données : le service Web de liste peut renvoyer tous les ensembles de données OSG disponibles. La liste des ensembles de données OSG peut être dynamique puisque le dépositaire OSG peut facilement en créer de nouveaux s'ils ont de la valeur. Pour obtenir une liste de tous les ensembles de données disponibles, y compris les champs de chaque ensemble de données pouvant être interrogés, la requête suivante peut être utilisée :
REPOS
Corps de la demande
{"listdatasets":{}}
Corps de réponse
"ListDataSetsResponseMessage":{
"Header":{
"ResultCount":8,
"ReturnCount":8,
"ErrorCode":0,
"ErrorMessage":"Success"
},
"NGListDataSetsResponseData":[
{"DataSet":"EST_STANDARD_SEARCH","Col":["Address_One_Line","Custodian","Easting","Northing","Parent_UPRN","Postcode","Search_Building_Name","Search_Building_No","Search_Postcode_No_Space","Search_Street_Name","Search_Town","Status","UPRN","USRN"]},
{"DataSet":"FVGIS_STANDARD_SEARCH","Col":["Address_One_Line","address_one_line_custom","County_Name","Custodian","Easting","Locality_Name","Northing","paon","PAO_NO","Postcode","Post_Town","p_text","record_type_id","saon","SAO_NO","search_building","search_building_name","search_building_no","search_street_name","search_town","Status","s_text","Street_Descriptor","Town","uprn","usrn","x_coordinate","y_coordinate"]},
{"DataSet":"FVGIS_STREET_SEARCH","Col":["Custodian","End_Easting","End_Northing","Local_Authority","Locality","search_street_name","search_street_town","Start_Easting","Start_Northing","Street_Name","street_one_line","Town","usrn"]},
{"DataSet":"GLASGOW_ACCESS_SAP","Col":["ADDRESS_ONE_LINE","ADR03","ADR04","FLOOR","LAND1","LOCALITY","ORT01","ORT02","PAO_NO","PSTLZ","P_TEXT","SAO_NO","search_line_one","search_postcode_no_space","STATE","S_TEXT","STREET_DESCRIPTOR","UPRN"]},
{"DataSet":"STANDARD_SEARCH","Col":["ADDRESS_ONE_LINE","Custodian","Easting","Northing","Postcode","search_building_name","search_building_no","search_street_name","search_town","Status","UPRN"]},
{"DataSet":"STANDARD_SEARCH_OLDP","Col":["address_one_line","Custodian","Easting","Northing","Postcode","search_building_name","search_building_no","search_postcode_no_space","search_street_name","search_town","Status","uprn"]},
{"DataSet":"STD_ADDRESS_SEARCH","Col":["ADD_LINE_1","ADD_LINE_2","ADD_LINE_3","address_string","la_code","POST_CODE","start_date","TOWN","UPRN","USRN","x_coord","y_coord"]},
{"DataSet":"WLC_SEARCH","Col":["Address_One_Line","address_one_line_custom","County_Name","Custodian","Easting","Locality_Name","Northing","paon","PAO_NO","Postcode","Post_Town","p_text","record_type_id","saon","SAO_NO","search_building","search_building_name","search_building_no","search_street_name","search_town","Status","s_text","Street_Descriptor","Town","uprn","usrn","x_coordinate","y_coordinate"]}
]
}
}
Requête : l'interrogation des données OSG implique l'utilisation du service Web de recherche et des champs ou/et des géométries. Le service Web de recherche peut recevoir les entrées suivantes :
Exemples REST
(1) Renvoie les enregistrements OSG de l'ensemble de données EST_STANDARD_SEARCH .
Corps de la demande
{"query":{
"dataset":"EST_STANDARD_SEARCH",
"type":"full"
}}
Corps de réponse
{
"SearchResponseMessage": {
"NGSearchResponseData": {
"Header": {
"ResultCount": 3296208,
"ReturnCount": 250,
"ErrorCode": 0,
"ErrorMessage": "Success"
},
"Result": {
"any": [
[CONTENT OMITTED DUE TO DATA LENGTH]
]
}
}
}
}
Tableau 1. Données de requête HTTP pouvant être incluses dans la requête publiée sur le service Web.
| Valeur | Description | Obligatoire | Taper |
|---|---|---|---|
dataset | Le nom de l'ensemble de données à interroger par le service web | Oui | string |
attribute | Un ou plusieurs attributs de l'ensemble de données qui peuvent être utilisés pour filtrer les résultats à renvoyer. Les attributs spécifiés doivent provenir des champs de l'ensemble de données. Un type de correspondance peut également être spécifié. Toutes les comparaisons ne sont pas sensibles à la casse. Pour l'attribut spécifié, un nom (du champ) et une ou plusieurs valeurs doivent être fournis. Plusieurs attributs sont appliqués tour à tour pour produire des ensembles plus petits de résultats à renvoyer (c'est-à-dire qu'ils sont logiquement regroupés). | Non | AttributeType |
area | Cela prend le nom d'un polygone préchargé qui peut être utilisé pour restreindre les résultats aux éléments avec un UPRN dans une zone géographique définie par ce polygone. | Non | string |
within | Si cet élément est fourni, il doit alors contenir trois sous-éléments, une ordonnée, une ordonnée et une distance. Ces éléments définissent une zone et seuls les éléments avec un UPRN dans cette zone sont renvoyés. | Non | WithinType |
sortField | Cela permet de trier les résultats sur l'un des champs de l'ensemble de données. La valeur fournie pour cela doit être l'un des champs de l'ensemble de données. | Non | string |
sortOrder | Appliqué au sortField | Non | SortOrderType |
Tableau 2. Définition de l' AttributeType
| Valeur | Taper | Possibilités |
|---|---|---|
matchtype | string | equal to (default) greater than greater than or equal to less than less than or equal to not equal to contains between in not in |
name | string | |
value | string |
Tableau 3. Définition du WithinType
| Valeur | Taper | Possibilités |
|---|---|---|
easting | unsignedLong | 0 - 500000 |
northing | unsignedLong | 500000 - 1300000 |
distance | decimal |
Tableau 4. Définition du SortOrderType
| Valeur | Taper | Possibilités |
|---|---|---|
asc | string | |
desc | string |
Tableau 5. Corps de réponse HTTP : inclut les données renvoyées dans le corps de réponse du serveur.
| Valeur | Description | Possibilités |
|---|---|---|
ResultCount | Le nombre d'éléments de données trouvés qui correspondent à la requête | |
ReturnCount | Le nombre d'éléments de données renvoyés par le service Web (le minimum de ResultCount et 250) | |
ErrorCode | Zéro pour le succès ou différent de zéro pour l'échec (voir plus tard) | Voir tableau "Codes d'erreur" |
ErrorMessage | Un message décrivant une erreur survenue (voir plus loin) | Voir tableau "Codes d'erreur" |
Result | Les éléments de données correspondant à la requête. Le format réel dépendra de l'ensemble de données interrogé, mais il sera constitué d'un ensemble d'éléments nommés de la même manière que l'ensemble de données, chaque élément contenant un élément pour chaque champ de l'ensemble de données (nommé de la même manière que ce champ). |
Tableau 6. Codes d'erreur de réponse HTTP : inclut tous les codes d'erreur possibles renvoyés par le serveur dans le corps de la réponse
Le service Web peut renvoyer quatre codes d'erreur possibles qui sont les suivants :
| Code | Explication | Message(s) |
|---|---|---|
0 | Soumission réussie au service Web | |
1 | Erreur avec les données publiées sur le service Web | Invalid Value - Schema validation error : <error msg> |
2 | Un problème est survenu lors du traitement de la demande (par exemple, demander un ensemble de données qui n'existe pas) | Invalid dataset [<dataset>] Invalid attribute name for dataset <dataset> [<attr_name>] <attr_name>: Invalid Date [<value>] expected format YYYY-MM-DD <attr_name>: Invalid Number [<value>] Invalid area [<area>] The dataset <dataset> does not support filtering on area polygon (<area>) awaiting initial index build - please try again later Invalid sort_field for dataset <dataset> [<sort_field>] |
3 | Erreur d'authentification/autorisation | Invalid Username/Password The address your computer is accessing this site from (xxx.xxx.xxx.xxx) has been blocked due to excessive failed login attempts. To have this block removed, please contact <contact email>. Alternatively, the block will be automatically removed in two hours time An unknown login failure occurred. The administrators have been notified of the event You do not have permission to use this service Missing authentication header in soap request |
