-
Notifications
You must be signed in to change notification settings - Fork 45
Export Tool API
/api/jobs
Main endpoint for export creation and managment. Provides endpoints for creating, listing and deleting export jobs.
Updates to existing exports are not supported as exports can be cloned.
POST /api/jobs
Request data can be posted as either application/x-www-form-urlencoded or application/json. Returns 202 Accepted if the request is correct.
Request parameters:
- name (required): The name of the export.
- description (required): A description of the export.
- event: The project or event associated with this export, eg Nepal Activation.
- xmin (required): The minimum longitude coordinate.
- ymin (required): The minimum latitude coordinate.
- xmax (required): The maximum longitude coordinate.
- ymax (required): The maximum latitude coordinate.
-
formats (required): One of the supported export formats (html or json).
- Use the format
slugas the value of the formats parameter, egformats=thematic&formats=shp.
- Use the format
-
preset: One of the published preset files (html or json).
- Use the
uidas the value of the preset parameter, egpreset=eed84023-6874-4321-9b48-2f7840e76257. - If no preset parameter is provided, then the default HDM tags will be used for the export.
- Use the
-
published:
trueif this export is to be published globally,falseotherwise.- Unpublished exports will be purged from the system 48 hours after they are created.
This example will create a publicly published export using the default set of HDM tags for an area around Dar es Salaam, Tanzania. The export will create thematic shapefile, shapefile and kml files.
{
"name": "Dar es Salaam",
"description": "A description of the test export",
"event": "A HOT project or activation",
"xmin": 39.054879,
"ymin": -7.036697,
"xmax": 39.484149,
"ymax": -6.610281,
"formats": ["thematic", "shp", "kml"],
"published": "true"
}To create an export with a default set of tags, save the example json request to a local file called request.json and run the following command from the directory where the file is saved. You will need an access token. We can provide this on request.
curl -v -H "Content-Type: application/json" -H "Authorization: Token [your token]"
--data @request.json http://export.hotosm.org/api/jobs
To monitor the resulting export Run retrieve the uid value from the returned json
and use the Run API. See Retrieve Export API for example of return format.
GET /api/jobs
Returns a JSON array of exports.
Request parameters
- page_size: The number of results to return per page (default 10).
- page: The page of results to return.
The response will contain Link and Content-Range headers which can be used for pagination, for example:
Link:<http://export.hotosm.org/api/jobs.json?page=6&page_size=2>; rel="next", <http://export.hotosm.org/api/jobs.json?page=4&page_size=2>; rel="prev"
Content-Range: results 9-10/42
The returned JSON has the following format:
[
{
"uid": "23a794ce-316e-48f1-891a-da44436dfb00",
"url": "http://export.hotosm.org/api/jobs/23a794ce-316e-48f1-891a-da44436dfb00",
"name": "Dar es Salaam",
"description": "A description of the test export",
"event": "",
"created_at": "2015-10-14T13:38:26.473511Z",
"owner": "the_owner",
"extent": {
"type": "Feature",
"properties": {
"uid": "23a794ce-316e-48f1-891a-da44436dfb00",
"name": "Dar es Salaam"
},
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
39.054879,
-7.036697
],
[
39.054879,
-6.610281
],
[
39.484149,
-6.610281
],
[
39.484149,
-7.036697
],
[
39.054879,
-7.036697
]
]
]
}
},
"region": {
"uid": "c5d55b6e-73c0-4c0d-87af-c4c74afb6a15",
"name": "Africa",
"description": "African region",
"url": "http://export.hotosm.org/api/regions/c5d55b6e-73c0-4c0d-87af-c4c74afb6a15"
},
"published": false
},
]Get /api/export_uid
Return the export with the specified uid. Returns a more detailed representation than the list api.
curl -v -H "Content-Type: application/json" -H "Authorization: Token [your token]" http://export.hotosm.org/api/jobs/aedc2fdf-35a9-4c08-956c-6089d6b2f6dd
{
"uid": "aedc2fdf-35a9-4c08-956c-6089d6b2f6dd",
"url": "http://export.hotosm.org/api/jobs/aedc2fdf-35a9-4c08-956c-6089d6b2f6dd",
"name": "Dar es Salaam",
"description": "A description of the test export",
"event": "A HOT project or activation",
"created_at": "2015-10-14T12:49:18.264186Z",
"owner": "the_owner",
"exports": [
{
"uid": "317acc7d-daa8-4699-beba-b274cb59c99d",
"url": "http://export.hotosm.org/api/formats/obf",
"slug": "obf",
"name": "OBF Format",
"description": "OSMAnd OBF"
},
{
"uid": "c81bab45-e0fc-4cc4-ba1e-58964b4e9fcf",
"url": "http://export.hotosm.org/api/formats/shp",
"slug": "shp",
"name": "ESRI Shapefile Format",
"description": "Esri SHP (OSM Schema)"
},
{
"uid": "db68fa20-8336-4a8c-8557-a6ac7abec52e",
"url": "http://export.hotosm.org/api/formats/kml",
"slug": "kml",
"name": "KML Format",
"description": "Google Earth KMZ"
},
],
"configurations": [],
"published": false,
"feature_save": false,
"feature_pub": false,
"region": {
"uid": "c5d55b6e-73c0-4c0d-87af-c4c74afb6a15",
"name": "Africa",
"description": "African region",
"url": "http://export.hotosm.org/api/regions/c5d55b6e-73c0-4c0d-87af-c4c74afb6a15"
},
"extent": {
"type": "Feature",
"properties": {
"uid": "aedc2fdf-35a9-4c08-956c-6089d6b2f6dd",
"name": "Dar es Salaam"
},
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
39.054879,
-7.036697
],
[
39.054879,
-6.610281
],
[
39.484149,
-6.610281
],
[
39.484149,
-7.036697
],
[
39.054879,
-7.036697
]
]
]
}
},
"tags": [
{
"key": "building",
"value": "yes",
"data_model": "HDM",
"geom_types": [
"polygon"
]
},
{
"key": "building",
"value": "residential",
"data_model": "HDM",
"geom_types": [
"polygon"
]
},
{
"key": "building",
"value": "school",
"data_model": "HDM",
"geom_types": [
"polygon"
]
},
{
"key": "building",
"value": "stadium",
"data_model": "HDM",
"geom_types": [
"polygon"
]
},
{
"key": "building",
"value": "industrial",
"data_model": "HDM",
"geom_types": [
"polygon"
]
},
]
}DELETE /api/jobs/job_uid
Deletes the export with the specified job_uid. Returns 204 No Content if export is successfully deleted. Returns 403 Forbidden if the user is not the owner of the export and does not have permission to delete it.
curl -v -H 'Authorization: Token your_token_here' -X DELETE http://export.hotosm.org/api/jobs/job_uid
Get /api/runs?job_uid=a_job_uid
Provides an endpoint for querying export runs. Export runs for a particular job can be filtered by status by appending one of COMPLETED, SUBMITTED, INCOMPLETE or FAILED as the value of the STATUS parameter: /api/runs?job_uid=a_job_uid&status=STATUS
[
{
"uid": "ec6e8d9c-8504-4c21-aa0d-34c063693e00",
"url": "http://export.hotosm.org/api/runs/ec6e8d9c-8504-4c21-aa0d-34c063693e00.json",
"started_at": "2015-10-20T09:07:39.642921Z",
"finished_at": "2015-10-20T09:08:29.829Z",
"duration": "0:00:50.186577",
"user": "the_user",
"status": "COMPLETED",
"job": {
"uid": "94790b13-ef9f-4b87-b283-c5a00d97241d",
"name": "Pondok Cabe Udik",
"description": "Pamulang",
"url": "http://export.hotosm.org/api/jobs/94790b13-ef9f-4b87-b283-c5a00d97241d.json",
"extent": {
"type": "Feature",
"properties": {
"uid": "94790b13-ef9f-4b87-b283-c5a00d97241d",
"name": "Pondok Cabe Udik"
},
"geometry": {
"type": "Polygon",
"coordinates": [
[
[
106.747799,
-6.349379
],
[
106.747799,
-6.345113
],
[
106.752048,
-6.345113
],
[
106.752048,
-6.349379
],
[
106.747799,
-6.349379
]
]
]
}
}
},
"tasks": [
{
"uid": "11efdd53-00ad-4f1e-8866-65a5870e4e76",
"url": "http://export.hotosm.org/api/tasks/11efdd53-00ad-4f1e-8866-65a5870e4e76.json",
"name": "OSM2PBF",
"status": "SUCCESS",
"started_at": "2015-10-20T09:07:43.518Z",
"finished_at": "2015-10-20T09:07:44.163Z",
"duration": "0:00:00.644521",
"result": {
"filename": "pondok_cabe_udik.pbf",
"size": "0.004 MB",
"url": "http://export.hotosm.org/downloads/ec6e8d9c-8504-4c21-aa0d-34c063693e00/pondok_cabe_udik.pbf"
},
"errors": [ ]
},
{
"uid": "a921dbc0-88a7-4c71-a579-9ef2bdc4e3b5",
"url": "http://export.hotosm.org/api/tasks/a921dbc0-88a7-4c71-a579-9ef2bdc4e3b5.json",
"name": "OSMSchema",
"status": "SUCCESS",
"started_at": "2015-10-20T09:07:44.361Z",
"finished_at": "2015-10-20T09:08:19.764Z",
"duration": "0:00:35.402822",
"result": {
"filename": "pondok_cabe_udik.sqlite",
"size": "4.252 MB",
"url": "http://export.hotosm.org/downloads/ec6e8d9c-8504-4c21-aa0d-34c063693e00/pondok_cabe_udik.sqlite"
},
"errors": [ ]
},
]
}
]GET /api/rerun?job_uid=a_job_uid
Re-runs an export job for the given job_uid. Returns json as per the Run API above.