Do your first spatial analysis
Go through all the steps, from declaring your dataset to query it with your first spatial requests.
- Major steps
- 1. Gather data from your GIS Team
- 2. Declare your datasets to the Woosmap service
- 3. Import/refresh at will the data in Woosmap DB
- 4. Check your datasets
- 5. Request your data with simple queries
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
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
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
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
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
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
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
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
You’re all set!
