-
Notifications
You must be signed in to change notification settings - Fork 3
/
api.html
411 lines (380 loc) · 18.9 KB
/
api.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
<!DOCTYPE HTML>
<!--
Verti by HTML5 UP
html5up.net | @ajlkn
Free for personal and commercial use under the CCA 3.0 license (html5up.net/license)
-->
<html>
<head>
<title>geoBoundaries</title>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no" />
<link rel="stylesheet" href="assets/css/main.css" />
<link rel="stylesheet" href="assets/css/tabulator.css">
<script type="text/javascript" src="assets/js/tabulator.js"></script>
<!-- Global site tag (gtag.js) - Google Analytics -->
<script async src="https://www.googletagmanager.com/gtag/js?id=UA-9276981-3"></script>
<script>
window.dataLayer = window.dataLayer || [];
function gtag() { dataLayer.push(arguments); }
gtag('js', new Date());
gtag('config', 'UA-9276981-3');
</script>
<!-- Global site tag (gtag.js) - Google Ads: 984002936 -->
<script async src="https://www.googletagmanager.com/gtag/js?id=AW-984002936"></script>
<script>
window.dataLayer = window.dataLayer || [];
function gtag(){dataLayer.push(arguments);}
gtag('js', new Date());
gtag('config', 'AW-984002936');
</script>
<!-- Event snippet for Website traffic conversion page -->
<script>
gtag('event', 'conversion', {'send_to': 'AW-984002936/BycZCJ_8kdMBEPjimtUD'});
</script>
</head>
<body class="is-preload left-sidebar">
<div id="page-wrapper">
<!-- Header & Nav -->
<div id="header-wrapper">
<header id="header" class="container">
<!-- Logo -->
<div id="logo">
<h1><a href="index.html">geoBoundaries</a></h1>
<span><a href="http://geolab.wm.edu">@ William & Mary</a></span>
</div>
<nav id="nav">
<ul>
<li>
<a href="visualize.html">Visualize Data</a>
</li>
<li>
<a href="index.html#features-wrapper">Download Data</a>
</li>
<li>
<a href="api.html">API</a>
</li>
<li>
<a href="contribute.html">Get Involved</a>
</li>
</ul>
</nav>
</header>
</div>
<!-- Main -->
<div id="main-wrapper">
<div class="container">
<div class="row gtr-200">
<div class="col-4 col-12-medium">
<div id="sidebar">
<!-- Sidebar -->
<section>
<h3>Archival & Programmatic Access</h3>
<p> The community has built a number of endpoints and tools to provision geoBoundaries programmatically. We encourage automated uses of geoBoundaries, and while we cannot guarantee uptime for our API, we have had relatively little downtime historically. <b><a href="index.html#usage">Attribution</a> is required for uses of geoBoundaries that leverage these tools</b>. </p>
<footer>
<div style="overflow:hidden;"><a href="api.html#archive" style="width:100%;position:relative;top:20px;padding-top:5px;padding-bottom:-10px;" class="button icon solid fa-history">Archival Access <span style="font-size:0.5em;position:relative;top:-15px;line-height:0px;left:30px;"><br />Research Replication</span></a></div>
<div style="overflow:hidden;"><a href="api.html#api" style="width:100%;position:relative;top:20px;padding-top:5px;padding-bottom:-10px;" class="button icon solid fa-plug">API <span style="font-size:0.5em;position:relative;top:-15px;line-height:0px;left:30px;"><br />Programmatic access into the database</span></a></div>
<!--<div style="overflow:hidden;"><a href="api.html#python" style="width:100%;position:relative;top:20px;padding-top:5px;padding-bottom:-10px;" class="button icon solid fa-file-code">Python <span style="font-size:0.5em;position:relative;top:-15px;line-height:0px;left:30px;"><br />Package & API Access with Python</span></a></div>
<div style="overflow:hidden;"><a href="api.html#R" style="width:100%;position:relative;top:20px;padding-top:5px;padding-bottom:-10px;" class="button icon solid fa-file">R <span style="font-size:0.5em;position:relative;top:-15px;line-height:0px;left:30px;"><br />R Library</span></a></div>-->
</footer>
</section>
</div>
</div>
<div class="col-8 col-12-medium imp-medium">
<div id="content">
<!-- Content -->
<h2 id="archive">Web-based Archival Access</h2>
<p> File access has been standardized on the github platform. To download
a file from the current release, you can navigate to our <a href="https://github.com/wmgeolab/geoBoundaries/commits/main">commits</a> page, and choose the date (and commit) you are interested in retrieving files from. For convenience and research replication purposes, we further provide yearly releases of geoBoundaries. Archives for each of those releases can be found in the below table. Archived data prior to 1.3.4 is largely unstructured, but is available on <a href="mailto:[email protected]">request</a>.
<div id="ADM0" class="box">
<table>
<tbody>
<tr>
<td><b>Release</b></td>
<td><b>Date</b></td>
<td><b>Single-country</b></td>
<td><b>CGAZ</b></td>
</tr>
<tr>
<td>geoBoundaries 5.0.0</td>
<td>December 19, 2022</td>
<td><i class='fa fa-flag'></i> <a href="https://github.com/wmgeolab/geoBoundaries/tree/b7dd6a55701c76a330500ad9d9240f2b9997c6a8">b7dd6a5</a></td>
<td><i class='fa fa-globe'></i> <a href="https://github.com/wmgeolab/geoBoundaries/tree/b7dd6a55701c76a330500ad9d9240f2b9997c6a8/releaseData/CGAZ">Download</a></td>
</tr>
<tr>
<td>geoBoundaries 4.0.0</td>
<td>August 31, 2021</td>
<td><i class='fa fa-flag'></i> <a href="https://github.com/wmgeolab/geoBoundariesArchive_4_0_0/tree/299e00623ece6c03bcb9a751eda6094b1eac85a6">299e006</a></td>
<td><i class='fa fa-globe'></i> <a href="https://github.com/wmgeolab/geoBoundariesArchive_4_0_0/tree/299e00623ece6c03bcb9a751eda6094b1eac85a6/releaseData/CGAZ">Download</a></td>
</tr>
<tr>
<td>geoBoundaries 3.0.0</td>
<td>June 5, 2020</td>
<td><i class='fa fa-flag'></i> <a href="https://github.com/wmgeolab/geoBoundariesArchive_3_0_0/tree/7c8dbc599e312d9204e450aecfa66c204b8cf9b8">7c8dbc5</a></td>
<td><i class='fa fa-globe'></i> <a href="https://github.com/wmgeolab/geoBoundariesArchive_3_0_0/tree/7c8dbc599e312d9204e450aecfa66c204b8cf9b8/releaseData/CGAZ">Download</a></td>
</tr>
<tr>
<td>geoBoundaries 2.0.0</td>
<td>December 7, 2019</td>
<td><i class='fa fa-flag'></i> <a href="https://github.com/wmgeolab/geoBoundariesArchive_2_0_1/tree/375ea48193eda78f74b964f1c898a04bd4cb465d">375ea48</a></td>
<td><i class='fa fa-globe'></i> N/A</td>
</tr>
<tr>
<td>geoBoundaries 1.3.3</td>
<td>August 30, 2018</td>
<td><i class='fa fa-flag'></i> <a href="https://github.com/wmgeolab/geoBoundariesArchive_1_3_3/tree/d3f7490211be2971214f355055629b0c2dedeef6">d3f7490</a></td>
<td><i class='fa fa-globe'></i> N/A</td>
</tr>
</tbody>
</table>
</div>
</p>
<br />
<h2 id="api">API Access to geoBoundaries</h2>
Information on every geoBoundary, including paths for geoJSONs, shapefiles, years of validity and more, can be retrieved through any http-compliant query; a JSON object is returned. We provide one endpoint for users:
<pre><code>https://www.geoboundaries.org/api/current/[RELEASE-TYPE]/[3-LETTER-ISO-CODE]/[BOUNDARY-TYPE]/</code></pre>
<ul>
<li>
<pre><code>[RELEASE-TYPE]</code></pre> This is one of gbOpen, gbHumanitarian, or gbAuthoritative. For most users, we suggest using gbOpen, as it is CC-BY 4.0 compliant, and can be used for most purposes so long as attribution is provided. gbHumanitarian files are mirrored from UN OCHA, but may have less open licensure. gbAuthoritative files are mirrored from UN SALB, and cannot be used for commerical purposes, but are verified through in-country processes.
</li>
<li>
<pre><code>[3-LETTER-ISO-CODE]</code></pre> This is a ISO-3166-1 (Alpha 3) code for the country of interest. For example, "USA" for the United States, "GBR" for the United Kingdom, "CHN" for China, etc. The special code "ALL" is also accepted.
</li>
<li>
<pre><code>[ADM-LEVEL]</code></pre> This is the type of boundary that you are interested in. Right now, we accept one of five different types: ADM0, ADM1, ADM2, ADM3, ADM4 and ADM5. ADM0 is the country boundary, ADM1 is the first level of subnational boundaries, ADM2 is the second level of subnational boundaries, and so on. For example, the United States has ADM0 (the country border), ADM1 (States), ADM2 (county) boundaries. The special code "ALL" is also accepted.
</li>
</ul>
Once a request is made, a JSON is returned which contains the following fields (all returned objects are represented as strings; if a columnn is not guaranteed, it may return an empty string):
<div id="ADM0" class="box">
<table style="font-size:0.75em;line-height:0.9em;">
<tbody>
<tr>
<td><b>Element</b></td>
<td><b>Guaranteed</b></td>
<td><b>Definition</b></td>
<td><b>Example</b></td>
</tr>
<tr>
<td>boundaryID</td>
<td>Yes</a></td>
<td><i>The ID for this layer, which is a combination of the ISO code, the boundary type, and a unique identifier for the boundary generated based on the input metadata and geometry. This only changes if the underlying data changes</i></td>
<td>"ALB-ADM0-26141361"</td>
</tr>
<tr>
<td>boundaryName</td>
<td>Yes</a></td>
<td><i>The name of the country the layer represents</i></td>
<td>"Albania"</td>
</tr>
<tr>
<td>boundaryISO</td>
<td>Yes</a></td>
<td><i>ISO-3166-1 (Alpha 3) code for the country</i></td>
<td>"ALB"</td>
</tr>
<tr>
<td>boundaryYearRepresented</td>
<td>Yes</a></td>
<td><i> The year, or range of years in "[START] to [END]" format, which the boundary layers represent</i></td>
<td>"2021" or "1995 to 2021"</td>
</tr>
<tr>
<td>boundaryType</td>
<td>Yes</a></td>
<td><i> The type of boundary</i></td>
<td>"ADM1"</td>
</tr>
<tr>
<td>boundaryCanonical</td>
<td>No</a></td>
<td><i> The canonical name of a given boundary</i></td>
<td>"Qarqet"</td>
</tr>
<tr>
<td>boundarySource</td>
<td>Yes</a></td>
<td><i>A comma-seperated list of the primary sources for the boundary</i></td>
<td>"OCHA ROSEA, South African Municipal Demarcation Board"</td>
</tr>
<tr>
<td>boundarySource</td>
<td>Yes</a></td>
<td><i>A comma-seperated list of the primary sources for the boundary</i></td>
<td>"OCHA ROSEA, South African Municipal Demarcation Board"</td>
</tr>
<tr>
<td>boundaryLicense</td>
<td>Yes</a></td>
<td><i>The original license that the dataset was released under by the primary source</i></td>
<td>"Creative Commons Attribution 3.0 Intergovernmental Organisations (CC BY 3.0 IGO)"</td>
</tr>
<tr>
<td>licenseDetail</td>
<td>No</a></td>
<td><i>Any notes regarding the license.</i></td>
<td>"License was confirmed by two parties and the official website provided in the metadata."</td>
</tr>
<tr>
<td>licenseSource</td>
<td>Yes</a></td>
<td><i>The URL of the primary source.</i></td>
<td>"data.humdata.org/dataset/south-africa-admin-level-1-boundaries"</td>
</tr>
<tr>
<td>sourceDataUpdateDate</td>
<td>Yes</a></td>
<td><i>The date the source information was integrated into the geoBoundaries repository.</i></td>
<td>"Wed Jun 9 14:10:43 2021"</td>
</tr>
<tr>
<td>buildDate</td>
<td>Yes</a></td>
<td><i>The date the source data was most recently standardized and built into a geoBoundaries release.</i></td>
<td>"Jan 05, 2023"</td>
</tr>
<tr>
<td>Continent</td>
<td>Yes</a></td>
<td><i>The continent the country is associated with.</i></td>
<td>"Africa"</td>
</tr>
<tr>
<td>UNSDG-region</td>
<td>Yes</a></td>
<td><i>The United Nations Sustainable Development Goals (SDG) region the country is associated with.</i></td>
<td>"Sub-Saharan Africa"</td>
</tr>
<tr>
<td>UNSDG-subregion</td>
<td>Yes</a></td>
<td><i>The United Nations Sustainable Development Goals (SDG) subregion the country is associated with.</i></td>
<td>"Southern Africa"</td>
</tr>
<tr>
<td>worldBankIncomeGroup</td>
<td>Yes</a></td>
<td><i>The World Bank income group the country is associated with.</i></td>
<td>"Upper-middle-income Countries"</td>
</tr>
<tr>
<td>admUnitCount</td>
<td>Yes</a></td>
<td><i>Count of administrative units in the file.</i></td>
<td>"1"</td>
</tr>
<tr>
<td>meanVertices</td>
<td>Yes</a></td>
<td><i>Mean number of vertices defining the boundaries of each administrative unit in the layer.</i></td>
<td>"282824.0"</td>
</tr>
<tr>
<td>minVertices</td>
<td>Yes</a></td>
<td><i>Minimum number of vertices defining a boundary.</i></td>
<td>"18365"</td>
</tr>
<tr>
<td>maxVertices</td>
<td>Yes</a></td>
<td><i>Maximum number of vertices defining a boundary.</i></td>
<td>"38176456"</td>
</tr>
<tr>
<td>minPerimeterLengthKM</td>
<td>Yes</a></td>
<td><i>The minimum perimeter length of an administrative unit in the layer, measured in kilometers (based on a World Equidistant Cylindrical projection).</i></td>
<td>"180.5741729203648"</td>
</tr>
<tr>
<td>meanPerimeterLengthKM</td>
<td>Yes</a></td>
<td><i>The mean perimeter length of all administrative units in the layer, measured in kilometers (based on a World Equidistant Cylindrical projection).</i></td>
<td>"540.32156874946843"</td>
</tr>
<tr>
<td>maxPerimeterLengthKM</td>
<td>Yes</a></td>
<td><i>The maximum perimeter length of an administrative unit in the layer, measured in kilometers (based on a World Equidistant Cylindrical projection).</i></td>
<td>"1584.804735999137"</td>
</tr>
<tr>
<td>meanAreaSqKM</td>
<td>Yes</a></td>
<td><i>The mean area of all administrative units in the layer, measured in square kilometers (based on a EASE-GRID 2 projection).</i></td>
<td>"5731.517972980774"</td>
</tr>
<tr>
<td>minAreaSqKM</td>
<td>Yes</a></td>
<td><i>The minimum area of an administrative unit in the layer, measured in square kilometers (based on a EASE-GRID 2 projection).</i></td>
<td>"545.4813798711891"</td>
</tr>
<tr>
<td>maxAreaSqKM</td>
<td>Yes</a></td>
<td><i>The maximum area of an administrative unit in the layer, measured in square kilometers (based on a EASE-GRID 2 projection).</i></td>
<td>"44231.22640471353"</td>
</tr>
<tr>
<td>staticDownloadLink</td>
<td>Yes</a></td>
<td><i>The static download link for the aggregate zip file containing all boundary information.</i></td>
<td></td>
</tr>
<tr>
<td>gjDownloadURL</td>
<td>Yes</a></td>
<td><i>The static download link for the geoJSON.</i></td>
<td></td>
</tr>
<tr>
<td>tjDownloadURL</td>
<td>Yes</a></td>
<td><i>The static download link for the topoJSON.</i></td>
<td></td>
</tr>
<tr>
<td>imagePreview</td>
<td>Yes</a></td>
<td><i>The static download link for the automatically rendered PNG of the layer.</i></td>
<td></td>
</tr>
<tr>
<td>simplifiedGeometryGeoJSON</td>
<td>Yes</a></td>
<td><i>The static download link for the simplified geoJSON.</i></td>
<td></td>
</tr>
</tbody>
</table>
</div>
<!--<br /><br />
<h2 id="python">Python</h2>
Today, there are two options for using geoBoundaries with python via our API. The first is a community-built python package, (NAME). The second is through direct access of the API itself.<br />
<b style="font-size:1.5em;">Package</b>
Package
<br />
<b style="font-size:1.5em;">Python with the API</b>
API
<br /><br />
<h2 id="R">R Library</h2>
R Library-->
</div>
</div>
</div>
</div>
</div>
<!-- Footer -->
<div data-include="_includes/footer.shtml"></div>
</div>
<!-- Scripts -->
<script src="assets/js/jquery.min.js"></script>
<script src="assets/js/jquery.dropotron.min.js"></script>
<script src="assets/js/browser.min.js"></script>
<script src="assets/js/breakpoints.min.js"></script>
<script src="assets/js/util.js"></script>
<script src="assets/js/main.js"></script>
<script src="assets/js/HTMLInclude.min.js"></script>
</body>
</html>