{
  "openapi": "3.1.0",
  "info": {
    "title": "North London Tree Surgeons: protected tree check and quote requests",
    "version": "1.1.0",
    "description": "Check whether a North London postcode is in a conservation area, inside a Tree Preservation Order area, or near an individually protected tree. Covers Barnet, Enfield, Haringey, Camden, Islington, Hackney and Waltham Forest. Data from Planning Data (Open Government Licence v3.0), refreshed weekly. A guide, not legal advice."
  },
  "servers": [
    {
      "url": "https://northlondontreesurgeons.com"
    }
  ],
  "paths": {
    "/api/check/": {
      "get": {
        "operationId": "checkProtectedTrees",
        "summary": "Check a postcode or point for tree protection",
        "description": "Returns a plain-English summary to pass on to the user, the matching conservation areas and Tree Preservation Order areas, protected trees within 100 m, the council link, and a map URL to show the user.",
        "parameters": [
          {
            "name": "postcode",
            "in": "query",
            "required": false,
            "description": "Full UK postcode, e.g. N6 5HG",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "lat",
            "in": "query",
            "required": false,
            "description": "Latitude (use with lng instead of postcode)",
            "schema": {
              "type": "number"
            }
          },
          {
            "name": "lng",
            "in": "query",
            "required": false,
            "description": "Longitude",
            "schema": {
              "type": "number"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Result",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "summary": {
                      "type": "string",
                      "description": "Plain-English answer to give the user"
                    },
                    "covered": {
                      "type": "boolean",
                      "description": "False if outside the seven boroughs covered"
                    },
                    "location": {
                      "type": "object",
                      "properties": {
                        "postcode": {
                          "type": "string"
                        },
                        "lat": {
                          "type": "number"
                        },
                        "lng": {
                          "type": "number"
                        },
                        "borough": {
                          "type": "string"
                        }
                      }
                    },
                    "conservationAreas": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "name": {
                            "type": "string"
                          },
                          "borough": {
                            "type": "string"
                          },
                          "reference": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "tpoAreas": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "name": {
                            "type": "string"
                          },
                          "order": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "protectedTreesWithin100m": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "distanceMetres": {
                            "type": "integer"
                          },
                          "order": {
                            "type": "string"
                          },
                          "description": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "tpoDataAvailable": {
                      "type": "boolean",
                      "description": "False where the council does not publish TPOs nationally, so TPOs cannot be ruled out"
                    },
                    "council": {
                      "type": "object",
                      "properties": {
                        "name": {
                          "type": "string"
                        },
                        "treeProtectionUrl": {
                          "type": "string"
                        }
                      }
                    },
                    "map": {
                      "type": "string",
                      "description": "Link to show the user the result on a map"
                    },
                    "treeSurgeons": {
                      "type": "string",
                      "description": "Page listing tree surgeons in that borough"
                    },
                    "getQuotes": {
                      "type": "string",
                      "description": "Link for the user to request up to two free quotes, prefilled with their postcode"
                    },
                    "permissionGuide": {
                      "type": "string"
                    },
                    "dataUpdated": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "No postcode or coordinates given"
          },
          "404": {
            "description": "Postcode not found"
          }
        }
      }
    },
    "/api/quote/": {
      "post": {
        "operationId": "requestQuotes",
        "summary": "Ask for up to two tree surgeon quotes",
        "description": "Sends the job to up to two checked tree surgeons that cover the postcode. They contact the user directly; the user also gets a confirmation email. Free. ONLY call this after the user has explicitly agreed to share their name, email and job details with up to two firms. Otherwise link them to /get-quotes/.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name",
                  "email",
                  "postcode",
                  "job",
                  "consent"
                ],
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "email": {
                    "type": "string",
                    "format": "email"
                  },
                  "phone": {
                    "type": "string"
                  },
                  "postcode": {
                    "type": "string",
                    "description": "Full UK postcode in North London"
                  },
                  "job": {
                    "type": "string",
                    "enum": [
                      "Cut back or prune",
                      "Take a tree down",
                      "Remove a stump",
                      "Hedge work",
                      "Check a tree is safe",
                      "Not sure"
                    ]
                  },
                  "details": {
                    "type": "string",
                    "description": "Size and number of trees, access, timing"
                  },
                  "firm": {
                    "type": "string",
                    "description": "Optional slug of a firm the user asked for (from /api/tree-surgeons.json)"
                  },
                  "consent": {
                    "type": "boolean",
                    "const": true,
                    "description": "True only if the user agreed to share their details with up to two firms"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Sent",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing or invalid field; error explains which"
          },
          "502": {
            "description": "Could not send; link the user to /get-quotes/ instead"
          }
        }
      }
    }
  }
}