Source: https://developers.woosmap.com/products/datasets-api/first-queries/

> For clean Markdown of any page, append `.md` to the page URL.

> For a complete documentation index, see https://developers.woosmap.com/llms.txt

# Do your first spatial analysis



This guide is designed to provide you with a first glance at how Datasets API works and what are the basics to
understand to make the best of it.

Prerequistes are for you to have a dedicated project already existing in the Woosmap Console, the Datasets product to
be enabled on it and a private key set with RW capabilities.

## Major steps

Your journey will be composed of 5 majors steps:

- **gathering** data internally to build your datasets and make them ready for the Woosmap Datasets API
- **declaring** your dataset to build your Woosmap datasets library
- **importing** and refreshing your datasets to make them usable in your processes
- **checking** and managing your datasets
- **requesting** your datasets to bring value to your user/business journeys

## 1. Gather data from your GIS Team

Datasets API is designed to run with Shapefile data. This type of data is usually created and managed by a GIS teams in
companies. According to the spatial analysis you want to add in your digital journey, ask for the suitable data from
your internal teams.

Make sure to compress the usual files composing a Shapefile (.shp, .dbf, .shx, etc.) in one .zip file respecting the
service limits.

Host this .zip file behind a publicly reachable URL in your own infrastructure. Hosting the data on your side allows you
to easily update it and make it available to the Woosmap service to be fetched periodically.

## 2. Declare your datasets to the Woosmap service

As standard and in order to organize your data, you'll need to name your dataset. Choose a name that describes best your
dataset to help you find it back easily when you'll have multiple ones ;)  
The declaration phase means making a request providing the complete URL where your .zip is hosted on your side.  
Responses to the request will confirm the declaration went well and provide:

- a **dataset ID**: this is the unique ID for your dataset in Woosmap
- a **reimport key**: to be used to import/refresh the data in Woosmap from your hosted .zip file
- **creation / update / deletion dates**: informing on freshness of the data on Woosmap side

**POST** `/datasets/`  
See API reference for more details [here](/api-reference/datasets-api/post-datasets/)

## 3. Import/refresh at will the data in Woosmap DB

You're ready to actually import your dataset in Woosmap.

This import/refresh can either be triggered manually like when creating your first dataset, or be scheduled on your side
to make sure you get the most up-to-date data from your internal processes.  
To trigger this import, use the ID provided in the step 2 response.

**POST** `/datasets/{dataset_id}/import`  
See API reference for more details [here](/api-reference/datasets-api/post-datasets-dataset_id-import/)

## 4. Check your datasets

Once the Import/Refresh endpoint is triggered, and according to the size and the complexity of your dataset, the
import/refresh may take some time.  
Before performing your first requests, you can check the status of your dataset by requesting the dedicated endpoint
with the ID provided in the response of the import request.  
You'll get a detailed response with:

- the **steps** the import process is on and/or passed through
- the **dates** (start and end) associated to each steps
- a **status** for every step
- a **global status** for the full import/refresh process

**GET** `/datasets/{dataset_id}/status`  
See API reference for more details [here](/api-reference/datasets-api/get-datasets-dataset_id-status/)

If you have multiple datasets already loaded (trust us, you will have at some point ;P ), you can check the list of them.  
The dedicated endpoint provides the full list of datasets for a given project (same response as for the **step 2**).

At that point, you're almost ready to perform your first request to your newly imported dataset.

**GET** `/datasets/`  
See API reference for more details [here](/api-reference/datasets-api/get-datasets/)

## 5. Request your data with simple queries

Depending on your business cases, you may want to perform different spatial analysis either based on the location of
your users/visitors or on dynamic data retrieved along user journeys of your own.  
Datasets API provides **4 major spatial analysis** methods answering to those 4 different questions:

### Which feature of my dataset is nearby this geometry?

e.g. you are monitoring competitor settlements (your loaded dataset is composed of polygons or points materialising
competitor's site), and you want to retrieve nearby competitors from a new site of yours to come (you site location being
the geometry to test your dataset against).

**POST** `/datasets/{dataset_id}/features/nearby`  
See API reference for more details [here](/api-reference/datasets-api/post-datasets-dataset_id-features-nearby/)

### Which feature of my dataset is inside this geometry?

e.g. you are managing localised business information (location for your customers, offers, services) you want to be able
to retrieve thanks to polygons (geographic areas, zones, etc.)

**POST** `/datasets/{dataset_id}/features/within`  
See API reference for more details [here](/api-reference/datasets-api/post-datasets-dataset_id-features-within/)

### Which feature of my dataset is intersecting this geometry?

e.g. you are proposing car rental and want to inform of possible regulations or risks along your visitor's itinerary.
Triggers dedicated processes when itineraries (path calculated during your visitor journeys) intersect special zones
(your loaded dataset composed of polygons or lines materializing areas needing special awareness).

**POST** `/datasets/{dataset_id}/features/intersects`  
See API reference for more details [here](/api-reference/datasets-api/post-datasets-dataset_id-features-intersects/)

### Which feature of my dataset is containing this geometry?

e.g. you are proposing services, goods or real estate properties (dynamic data handled along the user journeys you're
proposing) and want to adapt the answer provided to your users based on specific geographic areas (regulation zones,
risk zones, tax zones, etc. you would have loaded as dataset to request against location your users would provide)

**POST** `/datasets/{dataset_id}/features/contains`
See API reference for more details [here](/api-reference/datasets-api/post-datasets-dataset_id-features-contains/)

**You're all set!**