one scotland gazetteer
1.0.0
Este repositorio incluye dos cosas:
(A) Código, ejemplos y scripts de Python 3.x para probar los servicios web de One Scotland Gazetteer (OSG) y la descarga FTP.
(B) Documentación general para los servicios web OSG y FTP.
(A) Ha instalado Python 3.x en su sistema operativo (OS)
(B) Se ha registrado en One Scotland Gazetteer (OSG) y puede estar autorizado a utilizar el servicio web de OSG o el FTP de OSG. Para obtener más información, visite el sitio web de One Scotland Gazetteer.
(A) Edite el development.ini :
En la carpeta raíz de este repositorio, edite el archivo development.ini y agregue su nombre de usuario y contraseña para el FTP de OSG y los servicios web de OSG. Estas credenciales las proporciona el custodio de One Scotland Gazetteer y es posible que usted tenga diferentes para los servicios FTP y web.
(B) Utilice los ejemplos de servicios web:
python rest.py
(C) Utilice la funcionalidad FTP ejecutando lo siguiente
python download_osg_using_ftp.py
Descripción general: esta documentación proporciona información sobre cómo utilizar mediante programación dos de los servicios "One Scotland Gazetteer" (OSG):
(1) servicio web; El servicio web se comunica directamente con la base de datos OSG y permite acceder al nomenclátor en tiempo real, brindando la información más actualizada. OSG admite dos tipos de servicios; la "Transferencia de estado representacional" (REST) y el "Protocolo simple de acceso a objetos" (SOAP).
(2) Exportar archivos; Se puede proporcionar una exportación en el formato escocés de transferencia de datos (SDTF) como un archivo CSV. Las exportaciones se programarán para que se ejecuten con una frecuencia predeterminada. También se puede suministrar un subconjunto de datos para satisfacer sus necesidades.
Para obtener información adicional, visite el sitio web de One Scotland Gazetteer.
Los servicios web de OSG están estructurados en torno a conjuntos de datos , que contienen campos que a su vez contienen los datos reales. Cada conjunto de datos de servicios web devuelve diferentes campos y datos y también puede admitir diferentes funciones. El OSG tiene dos servicios web sendNGListDataSetsMessage (en adelante lista ) que devuelve los conjuntos de datos disponibles para consultar, y sendNGSearchMessage (en adelante búsqueda ) que permite realizar consultas en esos conjuntos de datos. El recuento máximo de registros devueltos por los servicios web de OSG no puede exceder 250 . Las descripciones de los servicios OSG se pueden encontrar en REST y SOAP respectivamente.
Autenticación: todos los servicios web de OSG requieren autenticación mediante un username y una password . Se deben proporcionar tanto username como la password en los HTTP request headers para cada solicitud enviada al servicio web. A continuación se puede encontrar un ejemplo de los encabezados de solicitud de autenticación para REST y SOAP que utilizan credenciales falsas:
DESCANSAR
Content-Type:application/json
Accept:application/json
username:Alice
password:secret
JABÓN
<soapenv:Header>
<v0:HeaderLogin>
<username>Alice</username>
<password>secret</password>
</v0:HeaderLogin>
</soapenv:Header>
Autorización: La autenticación con el servicio web OSG utilizando su username y password no significa que tenga acceso a todos los conjuntos de datos OSG disponibles. El custodio de OSG administra el acceso a los conjuntos de datos y, si se necesita acceso a conjuntos de datos adicionales, los usuarios deben visitar el sitio web de One Scotland Gazetteer y presentar una solicitud. Por ejemplo, un usuario autenticado exitosamente puede estar autorizado a acceder al servicio web de búsqueda ( sendNGSearchMessage ) solo con el conjunto de datos EST_STANDARD_SEARCH pero no con el conjunto de datos ADDRESS_SEARCH .
Conjuntos de datos: el servicio web de lista puede devolver todos los conjuntos de datos OSG disponibles. La lista de conjuntos de datos de OSG puede ser dinámica, ya que el custodio de OSG puede crear fácilmente otros nuevos si tienen valor. Para obtener una lista de todos los conjuntos de datos disponibles, incluidos los campos para cada conjunto de datos que se puede consultar, se puede utilizar la siguiente solicitud:
DESCANSAR
Cuerpo de la solicitud
{"listdatasets":{}}
Cuerpo de respuesta
"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"]}
]
}
}
Consulta: Consultar los datos OSG incluye el uso del servicio web de búsqueda y campos o/y geometrías. El servicio web de búsqueda puede recibir las siguientes entradas:
Ejemplos de descanso
(1) Devuelve registros OSG del conjunto de datos EST_STANDARD_SEARCH .
Cuerpo de la solicitud
{"query":{
"dataset":"EST_STANDARD_SEARCH",
"type":"full"
}}
Cuerpo de respuesta
{
"SearchResponseMessage": {
"NGSearchResponseData": {
"Header": {
"ResultCount": 3296208,
"ReturnCount": 250,
"ErrorCode": 0,
"ErrorMessage": "Success"
},
"Result": {
"any": [
[CONTENT OMITTED DUE TO DATA LENGTH]
]
}
}
}
}
Tabla 1. Datos de solicitud HTTP que se pueden incluir en la consulta publicada en el servicio web.
| Valor | Descripción | Obligatorio | Tipo |
|---|---|---|---|
dataset | El nombre del conjunto de datos que consultará el servicio web. | Sí | string |
attribute | Uno o más atributos del conjunto de datos que se pueden utilizar para filtrar los resultados que se devolverán. Los atributos especificados deben provenir de los campos del conjunto de datos. También se puede especificar un tipo de coincidencia. Todas las comparaciones no distinguen entre mayúsculas y minúsculas. Para el atributo que se especifica, se debe proporcionar un nombre (del campo) y uno o más valores. Se aplican múltiples atributos a su vez para producir conjuntos más pequeños de resultados que se devolverán (es decir, se marcan juntos de manera lógica). | No | AttributeType |
area | Toma el nombre de un polígono precargado que se puede utilizar para restringir los resultados a elementos con un UPRN en un área geográfica definida por ese polígono. | No | string |
within | Si se proporciona este elemento, debe contener tres subelementos, un este, un norte y una distancia. Estos elementos definen un área y solo se devuelven los elementos con un UPRN en esa área. | No | WithinType |
sortField | Esto permite ordenar los resultados en uno de los campos del conjunto de datos. El valor proporcionado para esto debe ser uno de los campos del conjunto de datos. | No | string |
sortOrder | Aplicado al sortField | No | SortOrderType |
Tabla 2. Definición del AttributeType
| Valor | Tipo | Opciones |
|---|---|---|
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 |
Tabla 3. Definición de WithinType
| Valor | Tipo | Opciones |
|---|---|---|
easting | unsignedLong | 0 - 500000 |
northing | unsignedLong | 500000 - 1300000 |
distance | decimal |
Tabla 4. Definición de SortOrderType
| Valor | Tipo | Opciones |
|---|---|---|
asc | string | |
desc | string |
Tabla 5. Cuerpo de respuesta HTTP: Incluye los datos que se devuelven en el cuerpo de respuesta del servidor.
| Valor | Descripción | Opciones |
|---|---|---|
ResultCount | El número de elementos de datos encontrados que coinciden con la consulta. | |
ReturnCount | La cantidad de elementos de datos devueltos por el servicio web (el mínimo de ResultCount y 250) | |
ErrorCode | Cero para éxito o distinto de cero para fracaso (ver más adelante) | Ver tabla "Códigos de error" |
ErrorMessage | Un mensaje que describe un error que ocurrió (ver más adelante) | Ver tabla "Códigos de error" |
Result | Los elementos de datos que coinciden con la consulta. El formato real dependerá del conjunto de datos que se consulte, pero consistirá en un conjunto de elementos con el mismo nombre que el conjunto de datos, cada elemento contendrá un elemento para cada campo del conjunto de datos (con el mismo nombre que ese campo). |
Tabla 6. Códigos de error de respuesta HTTP: incluye todos los códigos de error posibles devueltos por el servidor en el cuerpo de la respuesta
El servicio web puede devolver cuatro posibles códigos de error que son los siguientes:
| Código | Explicación | Mensaje(s) |
|---|---|---|
0 | Envío exitoso al servicio web. | |
1 | Error con los datos publicados en el servicio web | Invalid Value - Schema validation error : <error msg> |
2 | Se encontró un problema durante el procesamiento de la solicitud (por ejemplo, al solicitar un conjunto de datos que no existe) | 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 | Error de autenticación/autorización | 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 |
