All Collections
Tools & Features
Data
Technical Guide: Integration API
Technical Guide: Integration API

Technical guidance for our Integration API - encrypted data sharing from Land App to external databases. To learn more, please contact sales

Simla Rees-Moorlah avatar
Written by Simla Rees-Moorlah
Updated over a week ago

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.5. As such, we would welcome any feedback, ideas, and suggestions from our API users for continued improvements, enhanced capabilities, or enriched data attribution.

note: during the upgrade to v1.4 (September 2022), Land App is now referring to "projects" as "plans". With respect to the API, these two are synonymous, thus the API calls will remain using the term "projects".

note: for users of the FME Software Package (by Safe Software), we have now created a "LandAppConnector" that is available in the FME Hub, which handles all the below guidance on your behalf. To learn more about the LandAppConnector, see here.


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 plan 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 plans or features.


4. Endpoints details


4.1. Endpoints to load plans


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


4.1.1. Request


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 plan

LAND_MANAGEMENT – Land management plan

SFI2022 - Sustainable Farm Incentive 22 (SFI 22)

SFI2023 - Sustainable Farm Incentive 23 (SFI 23)*

PEAT_ASSESSMENT - Peat Condition Assessment

OSMM - Ordnance Survey MasterMap

FER - Farm Environment Record

WCT - Woodland Creation Template

*Please note the API uses a search function, so by not using the entire string (e.g. "SFI" will return data from multiple templates containing the same string, "SFI2022" and "SFI2023").

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 plans in the results are created, modified, or archived 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=published – (optional) if given with published value then the endpoint instead of returning all the plans created on the organisation’s maps will return plans currently published in the organisation (same as those displayed in Map of maps). Please note that the results will include published projects shared outside the organisation, via the Collaboration functionality

excludeArchived=true - (optional) removes any archived plans from the request, returning only plans that remain unarchived

Example requests:


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

Attributes in response:

  • id - unique id for the project/plan

  • name - name of the project/plan

  • createdAt - date which the project/plan was first created

  • updatedAt - date which the project/plan was last edited

  • deletedAt - date which the project/plan was archived

  • map - unique id for the map containing the project/plan

  • mapName - name of the map containing the project/plan

Response model:

{
"page": number
"size": number,
"hasNext": boolean,
"data": [
{
"updatedAt": string (ISO DATE),
"id": string,
"name": string,
"createdAt": string (ISO DATE),
"archivedAt": 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 plans 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 plan not just those modified from a particular point in time as with the endpoint to load plans.


4.2.1. Request


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:


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"
}
},
...
]
}

General Structure (all templates):

Land App Attribute

Description

parcelId

The 4-character long numeric string (e.g. 5678) identifies the field parcel number. Concatenated automatically with parcelId to create "Field Number" (e.g. AB1234 5678)

sheetId

The 6-character long alpha-numeric string (e.g. AB1234) identifies the grid reference number of the parcel number. Concatenated automatically with sheetId to create "Field Number" (e.g. AB1234 5678)

description

An unlimited character string that sits as a description of the feature.

name

An unlimited character string that sits as a name of the feature.

laFeatureType

The defining attribute code that styling and attribution run off. For each project template, this must match the schema exactly. For each project template, "laFeatureType" is unique. For example, on the Countryside Stewardship template, "laFeatureType" is the CSS code such as "AB15" or "GS2". For Baseline Habitat Assessment or Land Management Plan, the "laFeatureType" is the UKHab Code, such as "g1" or "c1a6".

area

This field is automatically generated and calculated by Land App. If a file with this field is already populated, the Land App will not auto-calculate and errors may arise.

perimeter

This field is automatically generated and calculated by Land App. If a file with this field is already populated, the Land App will not auto-calculate and errors may arise.

UKHab Specific (Baseline Habitat Assessment or Land Management Plan)
The above plus:

Land App Attribute

Description

laScore

Condition assessments, stored as a categorical value, either: "Good", "Fairly Good", "Moderate", "Fairly Poor" or "Poor".

laSecCodes

Secondary Codes, stored as nested values, using just the numeric value for each unique Secondary code, started with {0}, e.g.

for 3 Secondary codes:
laSecCodes{0} = "60"

laSecCodes{1} = "120"

laSecCodes{2} = "121"

etc. (making a new attribute for each secondary code)

A look-up of what these codes represent can be downloaded from the UKHab website here.

Did this answer your question?