1. Introduction


This document provides guidance on how to use the Land App’s Integration API (“the Service”) in our production environment. The Service was launched on 1st December 2020 and is available to customers who have subscribed to our team management function. The current version of the Service is v1.3. As such, we would welcome any feedback, ideas, and suggestions from our API users for continued improvements, enhanced capabilities, or enriched data attribution.


2. Authentication


There is currently one method of authentication for use of the Service: an API Key. Your API Key is a unique identifier linked to the organisation account you have created on our team management function.

For future versions of the Service, we will look to add authentication capability based on OAuth2 Tokens. However, we are keen to learn more about the requirements and the tokens policies that our API users would like us to provide. The most important considerations for us to assess future authentication requirements are:

  • Is there a need for distinguishing the users that call the API?

  • Is there a need for any roles assigned to access tokens?

  • Do you have any preference on how long access token should be valid?


3. Pagination


The Service consists of two REST endpoints. The first REST endpoint provides the ability to load data from project layers. The second REST endpoint provides the ability to load data of individual features.

Both endpoints use pagination. The Service does not return all data at once. Instead, an API user must request each subsequent page of data – provided such data exist. The Service responses are wrapped in the following structure:

{ 
"page": 0,
"size": 10,
"hasNext": true,
"data": [
...
]
}

First attribute page in the structure is the number of the current page that you received, starting from 0.

Second attribute size represents the size of the page that was passed as a parameter.

Page and size attributes are parameters given to the endpoint. You can decide which page and what size you want to load. Although there is a limit on size parameter that you can set. This limit is different for each endpoint and its exact values will be given by each endpoint.

hasNext is Boolean value that indicates if the next page exists. You can use it in the loop condition to determine if further requests (with the incremented page) are needed.

Data is an array of projects or features.


4. Endpoints details


4.1. Endpoints to load projects


This endpoint gives you the ability to load all the projects created, updated, or deleted in your organisation from a particular point in time.


4.1.1. Request


URL: https://integration-api.thelandapp.com/projects

HTTP Method: GET

Parameters type: URL query params

Parameters:

apiKey – (mandatory) API key generated by The Land App for your organisation

type – (mandatory) projects type, use code of one of:

BPS – Basic Payment Scheme

CSS – Countryside Stewardship

FRM – Field Risk Map

RLE1 – RLE1 form

OWNERSHIP – Ownership Boundary

FR1 – Land Registration (FR1)

SALES_PLAN – Sales Plan

VALUATION_PLAN – Valuation Plan

ESS – Environmental Stewardship

UKHAB – Baseline Habitat Assessment

USER – Blank user project

LAND_MANAGEMENT – Land management plan

from – (mandatory if filter parameter not given with published value) date in ISO format that indicates from which point in time you want to extract data. All the projects in the results are created, modified, or deleted after this date

page – (optional) number of the page (see 3. Functionality). Default value is 0

size – (optional) size of the page (see 3. Functionality). Default value is 100. Max value is 1000

filter – (optional) if given with published value then the endpoint instead of returning all the projects created on the organisation’s maps will return projects currently published in the organisation (same as those displayed in Map of maps). Please note that the results may also include the projects from maps shared via the Collaboration functionality

Example requests:

https://integration-api.thelandapp.com/projects?apiKey=&page=0&size=10&type=BPS&from=2020-10-01T06:00:00.000Z

https://integration-api.thelandapp.com/projects?apiKey=&page=0&size=10&type=BPS&filter=published


4.1.2 Response


Response HTTP codes:

- 200 if all OK

- 400 if request is wrong (proper message why it is wrong is provided)

- 500 if unhandled error on server-side occurs

Response model:

{
"page": number
"size": number,
"hasNext": boolean,
"data": [
{
"updatedAt": string (ISO DATE),
"id": string,
"name": string,
"createdAt": string (ISO DATE),
"deletedAt": string (ISO DATE) (optional)
},
...
]
}

Example response:

{
"page": 0,
"size": 10,
"hasNext": false,
"data": [
{
"updatedAt": "2020-03-23T15:29:00.342Z",
"id": "5e78d5b24321a00013d022c9",
"name": "BPS2",
"createdAt": "2020-03-23T15:28:50.000Z"
},
{
"updatedAt": "2020-04-02T10:51:02.958Z",
"id": "5e78d5a14321a00013d022c8",
"name": "BPS1",
"createdAt": "2020-03-23T15:28:33.797Z"
},
{
"updatedAt": "2020-05-18T14:02:57.344Z",
"id": "5da5d965f08d12001372d5c6",
"name": "Norney Farm Partnership",
"createdAt": "2019-10-15T14:36:21.347Z"
},
{
"updatedAt": "2020-07-23T12:24:55.642Z",
"id": "5df9f867e3f0c200123b5687",
"name": "Land Registry Parcels",
"createdAt": "2019-12-18T09:59:03.829Z"
}
]
}

4.2. Endpoint to load features


This endpoint allows you to get all the features assigned to projects from the first endpoint. Please be aware that this endpoint does not take any date parameter which means that it returns all the features assigned to the given project, not just those modified from a particular point in time as with the endpoint to load projects.


4.2.1. Request


URL: http://integration-api.thelandapp.com/projects/<PROJECT_ID>/features

HTTP Method: GET

Parameters type: URL query params

Parameters:

  • PROJECT_ID – (mandatory) project id from the endpoint to load projects

  • apiKey – (mandatory) API key generated by The Land App for your organisation

  • page – (optional) number of the page (see 3. Functionality). Default value is 0.

  • size – (optional) size of the page (see 3. Functionality). Default value is 100 000. Max value is 100 000.

Example request:

http://integration-api.thelandapp.com/projects/features?apiKey=&page=0&size=1000


4.2.2. Response


Response HTTP codes:

- 200 if all OK

- 400 if the request is wrong (proper message why it is wrong is provided)

- 500 if unhandled error on server-side occurs

Response model:

{
"page": number
"size": number,
"hasNext": boolean,
"data": [
{
"type": GeoJSON feature type (e.g. "Feature"),
"id": number,
"geometry": {
"type": GeoJSON geometry type (e.g. "Geometry"),
"coordinates": array of numbers
},
"properties": structure of key-value pairs
},
...
]
}

Example response:

{ 
"page": 0,
"size": 1000,
"hasNext": false,
"data": [
{
"type": "Feature",
"id": 4685139,
"geometry": {
"type": "Polygon",
"coordinates": [ [ [ 494109.9, 144353.6799 ], [ 494110.2,
144353.7799 ], [ 494110.5, 144353.7799 ], ... ] ]
},
"properties": {
"sheetId": "SU9444",
"parcelId": "2136",
"name": "Feature name",
"isBpsEligible": false,
"code": "551",
"laFeatureType": "HS01"
}
},
...
]
}

Did this answer your question?