Geoplanning Webservices Documentation

Introduction

Geoplanning Webservices is a RESTful service for interacting with Goeplanning entities. It allows to create, read, update and delete entities and other specific actions such as start, stop, reject, … an activity.

HTTP verbs

Geoplanning Webservices tries to adhere as closely as possible to standard HTTP and REST conventions in its use of HTTP verbs.

Verb Usage

Verb	Usage
`GET`	Used to retrieve a resource
`POST`	Used to create a new resource
`PATCH`	Used to update an existing resource, including partial updates
`PUT`	Used to update an existing resource, full updates only
`DELETE`	Used to delete an existing resource

GET

Used to retrieve a resource

POST

Used to create a new resource

PATCH

Used to update an existing resource, including partial updates

PUT

Used to update an existing resource, full updates only

DELETE

Used to delete an existing resource

HTTP status codes

Geoplanning Webservices tries to adhere as closely as possible to standard HTTP and REST conventions in its use of HTTP status codes.

Status code Usage

Status code	Usage
`200 OK`	Standard response for successful HTTP requests. The actual response will depend on the request method used. In a GET request, the response will contain an entity corresponding to the requested resource. In a POST request, the response will contain an entity describing or containing the result of the action.
`201 Created`	The request has been fulfilled and resulted in a new resource being created.
`204 No Content`	The server successfully processed the request, but is not returning any content.
`400 Bad Request`	The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).
`404 Not Found`	The requested resource could not be found but may be available again in the future. Subsequent requests by the client are permissible.

200 OK

Standard response for successful HTTP requests. The actual response will depend on the request method used. In a GET request, the response will contain an entity corresponding to the requested resource. In a POST request, the response will contain an entity describing or containing the result of the action.

201 Created

The request has been fulfilled and resulted in a new resource being created.

204 No Content

The server successfully processed the request, but is not returning any content.

400 Bad Request

The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).

404 Not Found

The requested resource could not be found but may be available again in the future. Subsequent requests by the client are permissible.

Authentication

Every request must be authenticated with Geoplanning allowed credentials. Currently, only Basic Authentication is supported. Basic authentication is performed through an Authorization header with a base64 encoded value.

Example for login "test" and password 123 :

Header Value

Header	Value
`Authorization`	`Basic dGVzdDoxMjM=`

Authorization

Basic dGVzdDoxMjM=

To be allowed to use the Web Services, the user must be granted with at least the "webservices user" right.

Special headers

Every request sent to the API must come with the proper headers. The API requires two mandatory headers which are Accept and Content-Type as follow :

Header Value

Header	Value
`Accept`	`application/vnd.geoplanning-v3.0+json`
`Content-Type`	`application/vnd.geoplanning-v3.0+json`

Accept

application/vnd.geoplanning-v3.0+json

Content-Type

application/vnd.geoplanning-v3.0+json

Sending an address to Geoplanning

Submitting an address to Geoplanning can be tedious unless you know how it works.

Geoplanning needs 2 information about an address : it’s "administrative data" (country, post code, locality, street, number) and "geographic coordinates" (longitude, latitude). Providing only one, Geoplanning is able to compute the other but this comes with an accuracy issue.

If only the administrative data is provided, then Geoplanning will compute the coordinates of the closest address it finds with the provided data. This is called "geocoding". But, if either the input data is inaccurate/erroneous or our address database is incomplete the computed address might be different from the input address. In case of incomplete/erroneous input, this change is suitable and will correct the address, but in rare case it creates mistakes (when our database is incomplete). Therefore the geocoded address may be different from the input address and the created/updated entity at Geoplanning side may be different from what you submitted too.

If only the coordinates are provided, then Geoplanning will compute the administrative data of the closest address it finds to the provided coordinates. This is called "reverse geocoding". This process is efficient to get an approximative location of and address but not to get the exact administrative address of a location.

Long story short, if you can provide both administrative data and coordinates, do it. It will ensure that the imported data are exactly as provided, that is why the address structure is as follow :

Address structure

Field Type Description

Field	Type	Description
`longitude`	`Numeric`	Longitude coordinate of the address as decimal degree
`latitude`	`Numeric`	Latitude coordinate of the address as decimal degree
`country`	`String`	Country code according the ISO-2 standard for country names
`postcode`	`String`	Postal code of the address
`locality`	`String`	Locality name of the address
`street`	`String`	Street name of the address
`number`	`String`	House number in the street of the address

longitude

Numeric

Longitude coordinate of the address as decimal degree

latitude

Numeric

Latitude coordinate of the address as decimal degree

country

String

Country code according the ISO-2 standard for country names

postcode

String

Postal code of the address

locality

String

Locality name of the address

street

String

Street name of the address

number

String

House number in the street of the address

You can provide only the first two (longitude and latitude) but if you provide one, you must provide the other.

You can provide only the last four (country, postcode, locality, number) but if you provide one, you must provide the others.

Activity

Getting an activity

A GET request will retrieve an activity

Request structure

By Geoplanning ID

Unresolved directive in index.adoc - include::C:\_WORK\_JAVA\legacy\geoplanning\geoplanning-webservice\geoplanning-webservice-rest\target/generated-snippets/v3/activity/get/path-parameters.adoc[]

By reference

Unresolved directive in index.adoc - include::C:\_WORK\_JAVA\legacy\geoplanning\geoplanning-webservice\geoplanning-webservice-rest\target/generated-snippets/v3/activity/get/param/request-parameters.adoc[]