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*
UKHAB_V2 - Baseline Habitat Assessment (UKHab 2.0)*
USER – Blank user plan
LAND_MANAGEMENT – Land Management Plan*
LAND_MANAGEMENT_V2 - Land Management Plan (UKHab 2.0)*
SFI2022 - Sustainable Farm Incentive 22 (SFI 22)*
SFI2023 - Sustainable Farm Incentive 23 (SFI 23)*
SFI2024 - Sustainable Farm Incentive 24 (SFI 24)*
PEAT_ASSESSMENT - Peat Condition Assessment
OSMM - Ordnance Survey MasterMap
FER - Farm Environment Record
WCT - Woodland Creation Template
BLANK_SURVEY - General Data Collection (Mobile Survey)
*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{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. |