one scotland gazetteer

苏格兰地名词典

如何使用这个存储库

这个存储库包括两件事：

(A) 用于测试 One Scotland Gazetteer (OSG) Web 服务和 FTP 下载的 Python 3.x 代码、示例和脚本。

(B) OSG Web 服务和 FTP 的一般文档。

假设使用Python代码

(A)您已在操作系统 (OS) 中安装了 python 3.x

(B)您已在 One Scotland Gazetteer (OSG) 注册，并且您是否有权使用 OSG Web 服务或 OSG FTP。要了解更多信息，请访问苏格兰地名词典网站。

python代码使用说明

(A) 编辑development.ini ：

在此存储库的根文件夹中，编辑development.ini 文件并添加 OSG FTP 和 OSG Web 服务的用户名和密码。这些凭据由 One Scotland Gazetteer Custodian 提供，您对于 FTP 和 Web 服务可能有不同的凭据。

(B)使用 Web 服务示例：

python rest.py

(C)通过运行以下命令来使用 FTP 功能

python download_osg_using_ftp.py

文档

概述：本文档提供有关如何以编程方式使用两项“One Scotland Gazetteer”(OSG) 服务的信息：

(1)网络服务； Web 服务直接与 OSG 数据库通信，允许您实时访问地名词典，提供最新信息。 OSG支持两种类型的服务； “表述性状态传输”(REST) 和“简单对象访问协议”(SOAP)。

(2)导出文件；可以以苏格兰数据传输格式 (SDTF) 作为 CSV 文件导出。出口将按预定频率运行。还可以提供数据子集以满足您的要求。

欲了解更多信息，请访问 One Scotland Gazetteer 网站。

网络服务

OSG Web 服务是围绕数据集构建的，数据集包含字段，而字段又包含实际数据。每个 Web 服务数据集返回不同的字段和数据，并且还可能支持不同的功能。 OSG 有两个 Web 服务sendNGListDataSetsMessage （以下称为list ），它返回可用于查询的数据集；以及sendNGSearchMessage （以下称为search ），它允许对这些数据集执行查询。 OSG Web 服务返回的最大记录数不能超过250 条。 OSG 服务描述可以分别在 REST 和 SOAP 中找到。

身份验证：所有 OSG Web 服务都需要使用username和password进行身份验证。对于发送到 Web 服务的每个请求，都应在HTTP request headers中提供username和password 。下面是使用虚假凭证的 REST 和 SOAP 身份验证请求标头的示例：

休息

 Content-Type:application/json
Accept:application/json
username:Alice
password:secret

肥皂

 <soapenv:Header>
 <v0:HeaderLogin>
  <username>Alice</username>
  <password>secret</password>
 </v0:HeaderLogin>
</soapenv:Header>

授权：使用您的username和password通过 OSG Web 服务进行身份验证并不意味着您有权访问所有可用的 OSG 数据集。数据集的访问由 OSG 托管人管理，如果需要访问其他数据集，用户需要访问 One Scotland 地名词典网站并提出请求。例如，成功通过身份验证的用户可能被授权仅使用EST_STANDARD_SEARCH数据集而不是ADDRESS_SEARCH数据集访问搜索Web 服务 ( sendNGSearchMessage )。

数据集：列表Web服务可以返回所有可用的OSG数据集。 OSG 数据集列表可以是动态的，因为 OSG 托管人可以轻松创建新的数据集（如果它们有价值）。要获取所有可用数据集的列表，包括可查询的每个数据集的字段，可以使用以下请求：

休息

请求正文

 {"listdatasets":{}}

响应体

    "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"]}
            ]
        }
    }

查询：查询OSG数据包括使用搜索网络服务和字段或/和几何图形。搜索Web 服务可以接收以下输入：

休息示例

(1) 从EST_STANDARD_SEARCH数据集中返回 OSG 记录。

请求正文

 {"query":{
    "dataset":"EST_STANDARD_SEARCH",
    "type":"full"
}}

响应体

 {
    "SearchResponseMessage": {
        "NGSearchResponseData": {
            "Header": {
                "ResultCount": 3296208,
                "ReturnCount": 250,
                "ErrorCode": 0,
                "ErrorMessage": "Success"
            },
            "Result": {
                  "any": [ 
                      [CONTENT OMITTED DUE TO DATA LENGTH]
                         ]         
                      }
        }
    }
}

附录

表 1.可包含在发布到 Web 服务的查询中的 HTTP 请求数据。

价值	描述	强制的	类型
dataset	Web服务要查询的数据集的名称	是的	string
attribute	数据集的一个或多个属性，可用于过滤要返回的结果。指定的属性必须来自数据集中的字段。还可以指定匹配类型。所有比较都不区分大小写。对于指定的属性，必须提供（字段的）名称和一个或多个值。依次应用多个属性以生成要返回的较小结果集（即，它们在逻辑上被标记在一起）。	不	AttributeType
area	这采用预加载多边形的名称，该多边形可用于将结果限制为在该多边形定义的地理区域中具有 UPRN 的项目。	不	string
within	如果提供此元素，则它必须包含三个子元素：东距、北距和距离。这些元素定义一个区域，并且仅返回具有该区域中的 UPRN 的项目。	不	WithinType
sortField	这允许根据数据集中的字段之一对结果进行排序。为此提供的值必须是数据集中的字段之一。	不	string
sortOrder	应用于sortField	不	SortOrderType

表 2. AttributeType的定义

价值	类型	选项
matchtype	string	equal to (default) greater than greater than or equal to less than less than or equal to not equal to contains in between not in
name	string
value	string

表 3. WithinType的定义

价值	类型	选项
easting	unsignedLong	0 - 500000
northing	unsignedLong	500000 - 1300000
distance	decimal

表 4. SortOrderType的定义

价值	类型	选项
asc	string
desc	string

表 5. HTTP 响应正文：包括服务器响应正文中返回的数据。

价值	描述	选项
ResultCount	找到的与查询匹配的数据项的数量
ReturnCount	Web服务返回的数据项数量（ResultCount和250中的最小值）
ErrorCode	零表示成功，非零表示失败（见下文）	请参阅“错误代码”表
ErrorMessage	描述发生的错误的消息（见下文）	请参阅“错误代码”表
Result	与查询匹配的数据项。实际格式将取决于所查询的数据集，但它将由一组与数据集命名相同的元素组成，每个元素包含数据集中每个字段的元素（与该字段命名相同）。

表 6. HTTP 响应错误代码：包括服务器在响应正文中返回的所有可能的错误代码

Web 服务可以返回四种可能的错误代码，如下所示：

代码	解释	消息
0	成功提交到网络服务
1	发布到 Web 服务的数据出错	Invalid Value - Schema validation error : <error msg>
2	请求处理期间遇到问题（例如请求不存在的数据集）	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	认证/授权错误	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