diff --git a/docs/source/researcher/api.rst b/docs/source/researcher/api.rst new file mode 100644 index 00000000..936cafe9 --- /dev/null +++ b/docs/source/researcher/api.rst @@ -0,0 +1,23 @@ +.. _API Getting Started: + +Loading Seshat data in Python via the Seshat API +------------------------------------------------ + +You can access (and download) the latest Seshat data from the website using the Seshat API (Application Programming Interface). +The advantage of the API is that it allows you to access up-to-date Seshat data *programmatically*, allowing you to work with this data on your computer in a programming language such as Python. + +The best way to get started with loading data via the Seshat API is to use our Python package, which is available at `github.com/Seshat-Global-History-Databank/seshat_api `_. +If using the API for the first time, open the `examples` folder in the repository where you can find Jupyter notebooks that demonstrate how to use the API to load data in Python. +The README file in the `examples` folder provides instructions on how to install the package and run the examples. + +.. tip:: + + You may want to start by reading the `Software tools `_ page to ensure you have Python and Git installed on your computer. + + +.. note:: + + - The Seshat API is a RESTful API that allows you to query the Seshat database and retrieve data in JSON format. + - It is available on the Seshat website at `seshat-db.com/api `_. + - Loading the API in your browser will show you the available endpoints and the data that can be retrieved from them. + - There is a filter option that allows you to specify the data you want to retrieve from the API. \ No newline at end of file diff --git a/docs/source/researcher/cliopatria.rst b/docs/source/researcher/cliopatria.rst index e7269de4..922cca66 100644 --- a/docs/source/researcher/cliopatria.rst +++ b/docs/source/researcher/cliopatria.rst @@ -1,8 +1,29 @@ -How to edit the Cliopatria borders dataset -=========================================== +Cliopatria polity borders dataset +================================= Cliopatria is a comprehensive open-source geospatial dataset of worldwide states, political groups, events, and rulers from 3400BCE to 2024CE. It is part of the Seshat Global History Databank project. Presently it comprises over 1800 political entities sampled at varying timesteps and spatial scales. +Cliopatria is available as part of the Seshat database and API and is used on the `World Map `_ and polity pages of the Seshat website. + +Working with the Cliopatria borders dataset +-------------------------------------------- + +Cliopatria is available as a stand-alone dataset which is stored and documented at `github.com/Seshat-Global-History-Databank/cliopatria `_. +The data takes the form of a single GeoJSON file, a format that can be loaded by a wide variety of software for handling geospatial data. +Whilst Cliopatria can be accessed via the `Seshat API `_, in most cases it is faster and more convenient to download the dataset directly from the GitHub repository and work with it locally. + +A great way to get started exploring the Cliopatria dataset is to open it in the Jupyter notebook examples found inside the `github.com/Seshat-Global-History-Databank/cliopatria `_ GitHub repo. +The `notebooks` folder contains a processing script to add colors to the dataset, alongside a notebook which loads the data in GeoPandas and includes an interactive Folium plot. +There is also a notebook which loads Cliopatria and plots some stats about the dataset. +Follow the README instructions in the `notebooks` folder. + +.. tip:: + + You may want to start by reading the `Software tools `_ page to ensure you have Python and Git installed on your computer. + + +Cliopatria edit and release process +----------------------------------- Instructions for downloading, using and making new releases the dataset are available at the `Cliopatria GitHub repository `_. \ No newline at end of file diff --git a/docs/source/researcher/getting_started.rst b/docs/source/researcher/getting_started.rst index 4504211d..51e8bec4 100644 --- a/docs/source/researcher/getting_started.rst +++ b/docs/source/researcher/getting_started.rst @@ -76,44 +76,3 @@ If someone has assigned a comment to you: .. tip:: You can see all the polities with comments on them by visiting the `Polities with Comments `_ page. - - -.. _API Getting Started: - -Loading Seshat data in Python via the Seshat API ------------------------------------------------- - -You can access (and download) the latest Seshat data from the website using the Seshat API (Application Programming Interface). -The advantage of the API is that it allows you to access up-to-date Seshat data *programmatically*, allowing you to work with this data on your computer in a programming language such as Python. - -The best way to get started with loading data via the Seshat API is to use our Python package, which is available at `github.com/Seshat-Global-History-Databank/seshat_api `_. -If using the API for the first time, open the `examples` folder in the repository where you can find Jupyter notebooks that demonstrate how to use the API to load data in Python. -The README file in the `examples` folder provides instructions on how to install the package and run the examples. - -.. tip:: - - You may want to start by reading the `Software tools `_ page to ensure you have Python and Git installed on your computer. - - -.. note:: - - - The Seshat API is a RESTful API that allows you to query the Seshat database and retrieve data in JSON format. - - It is available on the Seshat website at `seshat-db.com/api `_. - - Loading the API in your browser will show you the available endpoints and the data that can be retrieved from them. - - There is a filter option that allows you to specify the data you want to retrieve from the API. - -Working with the Cliopatria borders dataset --------------------------------------------- - -The Cliopatria borders dataset is available as part of the Seshat database and API. It is used on the `World Map `_ and polity pages of the Seshat website. - -Cliopatria is also available as a stand-alone dataset which is stored and documented at `github.com/Seshat-Global-History-Databank/cliopatria `_. -The data takes the form of a single GeoJSON file, a format that can be loaded by a wide variety of software for handling geospatial data. - -A great way to get started exploring the Cliopatria dataset is to open it in the Jupyter notebook example found inside the `github.com/Seshat-Global-History-Databank/cliopatria `_ GitHub repo. -The `notebooks` folder contains a processing script to add colors to the dataset, alongside a notebook which loads the data in GeoPandas and includes an interactive Folium plot. -Follow the README instructions in the `notebooks` folder. - -.. tip:: - - You may want to start by reading the `Software tools `_ page to ensure you have Python and Git installed on your computer. \ No newline at end of file diff --git a/docs/source/researcher/index.rst b/docs/source/researcher/index.rst index bf4ef680..e06b6d48 100644 --- a/docs/source/researcher/index.rst +++ b/docs/source/researcher/index.rst @@ -11,6 +11,7 @@ You may also wish to review the `team <../team.rst>`_ page, which includes a hel :maxdepth: 3 getting_started + api datasets cliopatria projects