Skip to main content

​
Overview

The Planning API provides comprehensive access to planning application data across the UK, including:
  • Current and historic planning applications
  • Application status and decisions
  • Development categories and types
  • Appeals and enforcement notices
  • Associated documents and plans

​
Base URL

https://api.vepler.com/v1/planning

​
Authentication

All endpoints require authentication via API key: 
curl -H "x-api-key: YOUR_API_KEY" \
  https://api.vepler.com/v1/planning/{applicationId}

​
Available Endpoints

Get Application by ID

GET /v1/planning/{applicationId}

Query Applications

POST /v1/planning/query

Get by Source ID

GET /v1/planning/sources/{sourceId}

Health Check

GET /v1/planning/health

​
Quick Start

​
Search Planning Applications

import { Vepler } from 'vepler-sdk';

const vepler = new Vepler({ apiKey: process.env.VEPLER_API_KEY });

// Search for recent applications in Westminster
const applications = await vepler.planning.query({
  query: {
    councils: ['Westminster'],
    statuses: ['Approved', 'Pending'],
    receivedDateFrom: '2024-01-01',
    receivedDateTo: '2024-12-31'
  },
  limit: 25,
  sortBy: 'receivedDate',
  sortOrder: 'desc'
});

console.log(applications.data);
// [
//   {
//     id: 'plan_123',
//     reference: '24/00123/FULL',
//     address: '10 Downing Street, Westminster',
//     status: 'Approved',
//     receivedDate: '2024-03-15',
//     ...
//   }
// ]

​
Get Application Details

// Get by application ID
const application = await vepler.planning.get('plan_123');

// Get by council reference
const byReference = await vepler.planning.getBySource('westminster::24/00123/FULL');

console.log(application.data);
// {
//   id: 'plan_123',
//   reference: '24/00123/FULL',
//   council: 'Westminster',
//   status: 'Approved',
//   type: 'Full Planning Permission',
//   address: '10 Downing Street, Westminster, London SW1A 2AA',
//   postcode: 'SW1A 2AA',
//   description: 'Erection of single storey rear extension',
//   applicant: {
//     name: 'John Smith',
//     agent: 'ABC Architects Ltd'
//   },
//   dates: {
//     received: '2024-03-15',
//     validated: '2024-03-20',
//     decided: '2024-05-10',
//     expires: '2027-05-10'
//   },
//   decision: 'Granted',
//   developmentCategory: 'Householder',
//   documents: [...],
//   coordinates: {
//     latitude: 51.503363,
//     longitude: -0.127625
//   },
//   createdAt: '2024-03-15T10:30:00Z',
//   updatedAt: '2024-05-10T14:45:00Z'
// }

​
Query Parameters

The query endpoint supports comprehensive filtering:

​
Filter Parameters

ParameterTypeDescriptionExample
councilsstring[]Local planning authorities['Westminster', 'Camden']
statusesstring[]Application statuses['Approved', 'Refused']
typesstring[]Application types['Full', 'Outline']
developmentCategoriesstring[]Development categories['Residential', 'Commercial']
keystringKeyword search'extension'

​
Date Filters

ParameterTypeDescriptionExample
receivedDateFromstringStart date received'2024-01-01'
receivedDateTostringEnd date received'2024-12-31'
validatedDateFromstringStart date validated'2024-01-01'
validatedDateTostringEnd date validated'2024-12-31'
appealedDateFromstringStart date appealed'2024-01-01'
appealedDateTostringEnd date appealed'2024-12-31'

​
Sorting Options

ParameterTypeDefaultDescription
sortBystringreceivedDateField to sort by
sortOrderstringdescSort order: asc or desc
Available sort fields:
  • receivedDate - Date application received
  • validatedDate - Date application validated
  • decidedDate - Date decision made
  • address - Property address

​
Response Structure

{
  "data": {
    "id": "plan_123",
    "reference": "24/00123/FULL",
    "council": "Westminster",
    "ward": "St. James's",
    "status": "Approved",
    "type": "Full Planning Permission",
    "address": "10 Downing Street, Westminster, London SW1A 2AA",
    "postcode": "SW1A 2AA",
    "description": "Erection of single storey rear extension",
    "applicant": {
      "name": "John Smith",
      "company": null,
      "agent": "ABC Architects Ltd",
      "agentCompany": "ABC Architects Ltd"
    },
    "dates": {
      "received": "2024-03-15",
      "validated": "2024-03-20",
      "publicConsultationStart": "2024-03-21",
      "publicConsultationEnd": "2024-04-11",
      "targetDecision": "2024-05-15",
      "decided": "2024-05-10",
      "expires": "2027-05-10",
      "appealed": null
    },
    "decision": "Granted",
    "decisionType": "Delegated",
    "developmentCategory": "Householder",
    "developmentType": "Extension",
    "conditions": [
      {
        "number": 1,
        "description": "Development to begin within 3 years"
      },
      {
        "number": 2,
        "description": "Materials to match existing building"
      }
    ],
    "documents": [
      {
        "type": "Application Form",
        "url": "https://planning.westminster.gov.uk/document/123",
        "date": "2024-03-15"
      },
      {
        "type": "Plans",
        "url": "https://planning.westminster.gov.uk/document/124",
        "date": "2024-03-15"
      }
    ],
    "coordinates": {
      "latitude": 51.503363,
      "longitude": -0.127625
    },
    "propertyId": "p_0x000123456789",
    "createdAt": "2024-03-15T10:30:00Z",
    "updatedAt": "2024-05-10T14:45:00Z"
  }
}

​
Status Values

Common planning application statuses:
  • Pending - Application submitted but not validated
  • Validated - Application validated and consultation started
  • UnderConsideration - Being reviewed by planning officers
  • Approved - Application approved
  • ApprovedWithConditions - Approved with specific conditions
  • Refused - Application refused
  • Withdrawn - Applicant withdrew application
  • Appeal - Decision appealed
  • AppealAllowed - Appeal successful
  • AppealDismissed - Appeal unsuccessful

​
Development Categories

  • Residential - Houses, flats, residential developments
  • Commercial - Shops, offices, business premises
  • Industrial - Factories, warehouses, industrial units
  • Householder - Extensions, alterations to existing homes
  • ChangeOfUse - Changing property use class
  • Listed - Works to listed buildings
  • Conservation - Works in conservation areas
  • Trees - Tree works applications
  • Advertisement - Advertising consent
  • Telecommunications - Telecom masts and equipment

​
Pagination

Query results are paginated: 
const page1 = await vepler.planning.query({
  query: { councils: ['Westminster'] },
  limit: 50,
  offset: 0
});

const page2 = await vepler.planning.query({
  query: { councils: ['Westminster'] },
  limit: 50,
  offset: 50
});

​
Error Responses

{
  "error": {
    "code": "INVALID_DATE_RANGE",
    "message": "receivedDateFrom must be before receivedDateTo",
    "details": {
      "receivedDateFrom": "2024-12-31",
      "receivedDateTo": "2024-01-01"
    }
  }
}

​
Use Cases

Check planning history before purchase:
const history = await vepler.planning.query({
  query: {
    key: property.address,
    receivedDateFrom: '2020-01-01'
  }
});

const hasRefusals = history.data.some(
  app => app.status === 'Refused'
);
Monitor planning applications in your area:
const nearbyApplications = await vepler.planning.query({
  query: {
    councils: ['MyCouncil'],
    statuses: ['Pending', 'Validated'],
    receivedDateFrom: '2024-01-01'
  },
  sortBy: 'receivedDate',
  sortOrder: 'desc'
});
Analyze development trends:
const commercialDevelopments = await vepler.planning.query({
  query: {
    developmentCategories: ['Commercial'],
    statuses: ['Approved'],
    receivedDateFrom: '2023-01-01',
    receivedDateTo: '2023-12-31'
  }
});

const approvalRate = calculateApprovalRate(commercialDevelopments.data);

​
Rate Limits

Planning endpoints have the following limits:
  • Query endpoint: 500 requests/hour
  • Individual application: 1000 requests/hour

​
Next Steps

Query Applications

Search with advanced filters

Property API

Link planning to properties