Shapefiles


Jump to API response

Plotly allows the user to upload their Shapefiles to the Plotly servers, which can be rendered in Plotly Maps.

Plotly supports ESRI standard shapefiles, which should be uploaded only in zip format.

Reference

Authorization


Any user with or without a Plotly account may view public Shapefiles. For private files, see authentication.

Actions


upload

A Shapefile may be uploaded by making a POST request to the upload endpoint:

POST https://api.plotly.com/v2/shapefiles/upload

The following options may be passed as HTTP headers to control the upload.

  • X-File-Name: gives the filename of the Shapefile being uploaded.

  • Plotly-World-Readable: controls the visibility of the created Shapefile. May be true or false. Defaults to false.

  • Plotly-Parent: gives the parent folder id.

  • Plotly-Parent-Path: gives the path to the parent folder.


retrieve


A Single Shapefile can be retrieved by a GET Request to the shapefiles endpoint.

Example:

// GET https://api.plotly.com/v2/shapefiles/username:123


update

To completely replace the writable meta information of an existing shapefile, you make a PUT request to the shapefiles endpoint and include the fid for the shapefile.

Note, only the writable meta information may be updated. This includes filename, parent (or parent_path), and world_readable.

Note that parent_path may be specified in place of the parent field. Unlike parent, the parent_path field is not an integer id, but rather the complete path of the parent folder from your root folder (e.g., '/folder_nested_off_root/parent_folder/').

A successful PUT response will have a status code of 200 OK.

Example:

// PUT https://api.plotly.com/v2/shapefiles/bob:45 --> 200 OK
{
    "parent": -1,
    "world_readable": true,
    "filename": "my_new_filename",
    "content": "updated content"
}


partial update

To partially update an existing shapefile, you make a PATCH request to the shapefiles endpoint and include the fid for the shapefile.

Note, only the writable meta information may be updated. This includes filename, parent (or parent_path), and world_readable.

A successful PATCH response will have a status code of 200 OK.

Example:

// PATCH https://api.plotly.com/v2/shapefiles/bob:45 --> 200 OK
{
    "world_readable": true,
    "filename": "my_new_filename"
}


trash

This endpoint allows for the recoverable trashing of the shapefile specified in the endpoint detail.

A successful trash response will have a status code of 200 OK.

Example:

// POST https://api.plotly.com/v2/shapefiles/plotlvr:9/trash ---> 200 OK

This request is idempotent. Trashing a shapefile that is already trashed will also succeed and return 200 OK.


permanent_delete

This endpoint allows for the permanent deletion of the shapefile specified in the endpoint detail.

A successful deletion response will have a status code of 204 No Content.

Example:

// DELETE https://api.plotly.com/v2/shapefiles/plotlvr:9/permanent_delete ---> 204 No Content


GET /v2/shapefiles?format=api
HTTP 405 Method Not Allowed
Allow: GET, HEAD, OPTIONS
Content-Type: application/json
Vary: Accept

{
    "detail": "Listing all files not supported. Choose a file."
}