API Reference

UK drive time, distance, and postcode data. Three endpoints. One API key. No overages.

Introduction

The Job Bookers Routing API provides drive time and distance between any two UK postcodes, coordinate lookups for 1.7 million UK postcodes, and street name lookups. All data is computed from open, legally clean sources — OpenStreetMap road network data and ONS postcode coordinates.

The API is a straightforward REST API returning JSON. All requests are GET requests. Authentication is via a Bearer token in the Authorization header.

Authentication

Every request must include your API key as a Bearer token in the Authorization header.

HTTP header

Authorization: Bearer jbr_live_your_api_key_here

Your API key is issued by email when you subscribe. Keep it private — treat it like a password. If your key is compromised, email hello@jobbookers.co.uk and we will issue a replacement immediately.

Never expose your API key in client-side code. All requests to the Job Bookers API must be made server-side. If your key appears in browser JavaScript or a mobile app binary, it can be extracted and abused.

Base URL

https://api.jobbookers.co.uk/v1

All endpoints are served over HTTPS only. HTTP requests are redirected to HTTPS.

Rate limits

Your monthly call limit depends on your plan. Calls are counted against your monthly allocation which resets on the 1st of each month.

Plan	Monthly calls	Price
Starter	1,000	£19/month
Professional	10,000	£59/month
Business	50,000	£249/month

When you exceed your monthly limit, the API returns a 429 status with error code rate_limit_exceeded. There are no overage charges — usage simply stops until the next reset.

No caching permitted. Our Terms of Service prohibit caching API responses. Every routing query must call the API in real time. This protects the integrity of our data and ensures your pricing reflects actual usage.

Drive time & distance

GET /v1/route

https://api.jobbookers.co.uk/v1/route

Returns drive time in minutes and distance in miles between two UK postcodes.

Parameters

Parameter	Type	Required	Description
`from`	string	Yes	Origin UK postcode. e.g. `NR21 8AB`
`to`	string	Yes	Destination UK postcode. e.g. `PE37 7JL`

Example request

cURL

curl -X GET \
  "https://api.jobbookers.co.uk/v1/route?from=NR21+8AB&to=PE37+7JL" \
  -H "Authorization: Bearer jbr_live_your_api_key_here"

Example response

JSON — 200 OK

{
  "duration_mins": 22,
  "distance_miles": 14.3,
  "from_postcode": "NR21 8AB",
  "to_postcode": "PE37 7JL"
}

Postcode coordinates

GET /v1/geocode

https://api.jobbookers.co.uk/v1/geocode

Returns latitude and longitude for a UK postcode. Data from 1.7 million UK postcodes sourced from ONS postcode directory.

Parameters

Parameter	Type	Required	Description
`postcode`	string	Yes	UK postcode. e.g. `NR21 8AB`

Example request

cURL

curl -X GET \
  "https://api.jobbookers.co.uk/v1/geocode?postcode=NR21+8AB" \
  -H "Authorization: Bearer jbr_live_your_api_key_here"

Example response

JSON — 200 OK

{
  "postcode": "NR21 8AB",
  "lat": 52.8371,
  "lon": 0.8524
}

Full location lookup

GET /v1/location

https://api.jobbookers.co.uk/v1/location

Returns full location context for a UK postcode — street, town, county, state, country and coordinates — in a single call.

Parameters

Parameter	Type	Required	Description
`postcode`	string	Yes	UK postcode. e.g. `NR21 8AB`

Example request

cURL

curl -X GET \
  "https://api.jobbookers.co.uk/v1/location?postcode=NR21+8AB" \
  -H "Authorization: Bearer jbr_live_your_api_key_here"

Example response

JSON — 200 OK

{
  "postcode": "NR21 8AB",
  "street": "Walnut Grove",
  "town": "Fakenham",
  "county": "Norfolk",
  "state": "England",
  "country": "United Kingdom",
  "lat": 52.83162,
  "lon": 0.87049
}

Street name

GET /v1/street

https://api.jobbookers.co.uk/v1/street

Returns the street name for a given UK postcode.

Parameters

Parameter	Type	Required	Description
`postcode`	string	Yes	UK postcode. e.g. `NR21 8AB`

Example request

cURL

curl -X GET \
  "https://api.jobbookers.co.uk/v1/street?postcode=NR21+8AB" \
  -H "Authorization: Bearer jbr_live_your_api_key_here"

Example response

JSON — 200 OK

{
  "postcode": "NR21 8AB",
  "street": "Walnut Grove"
}

Error codes

All errors return a JSON body with a code and message field.

JSON — error response

{
  "error": {
    "code": "invalid_postcode",
    "message": "The postcode provided is not a valid UK postcode."
  }
}

HTTP status	Error code	Meaning
200	—	Success
400	`missing_postcode`	One or both postcode parameters not provided
400	`invalid_postcode`	Postcode format is not a valid UK postcode
401	`unauthorized`	API key missing or invalid
404	`not_found`	Postcode not found in dataset
429	`rate_limit_exceeded`	Monthly call limit reached
500	`server_error`	Unexpected server error — contact support
503	`routing_unavailable`	Routing engine temporarily unavailable

Postcode format

The API accepts UK postcodes in any standard format, with or without a space:

NR21 8AB — with space (preferred)
NR218AB — without space (accepted)
nr21 8ab — lowercase (accepted, normalised automatically)

The API normalises and validates postcodes before processing. If a postcode fails validation, a 400 invalid_postcode error is returned.

All UK postcode areas are supported including Scotland, Wales, Northern Ireland (BT postcodes), and Crown Dependencies.

Attribution

The Job Bookers Routing API is built on open data. If you display routing results in a product or service, you must include the following attributions:

Required attribution text

Routing data © OpenStreetMap contributors, available under the Open Database Licence.
Contains public sector information licensed under the Open Government Licence v3.0.

This can appear in your app footer, terms of service, or about page. It must not be hidden or removed.

cURL

cURL — drive time

curl -X GET \
  "https://api.jobbookers.co.uk/v1/route?from=NR21+8AB&to=PE37+7JL" \
  -H "Authorization: Bearer jbr_live_your_api_key_here" \
  -H "Accept: application/json"

JavaScript

JavaScript (Node.js / fetch)

// Server-side only — never expose your API key in browser code
const API_KEY = process.env.JBR_API_KEY;

async function getDriveTime(from, to) {
  const url = new URL('https://api.jobbookers.co.uk/v1/route');
  url.searchParams.set('from', from);
  url.searchParams.set('to', to);

  const res = await fetch(url, {
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Accept': 'application/json',
    },
  });

  if (!res.ok) {
    const err = await res.json();
    throw new Error(err.error?.message || 'API error');
  }

  return res.json();
  // { duration_mins: 22, distance_miles: 14.3, ... }
}

// Usage
const result = await getDriveTime('NR21 8AB', 'PE37 7JL');
console.log(`${result.duration_mins} mins, ${result.distance_miles} miles`);

Python

Python (requests)

import requests
import os

API_KEY = os.environ['JBR_API_KEY']
BASE_URL = 'https://api.jobbookers.co.uk/v1'

def get_drive_time(from_postcode, to_postcode):
    response = requests.get(
        f'{BASE_URL}/route',
        params={
            'from': from_postcode,
            'to': to_postcode,
        },
        headers={
            'Authorization': f'Bearer {API_KEY}',
            'Accept': 'application/json',
        },
        timeout=10
    )
    response.raise_for_status()
    return response.json()

# Usage
result = get_drive_time('NR21 8AB', 'PE37 7JL')
print(f"{result['duration_mins']} mins, {result['distance_miles']} miles")

PHP

PHP (cURL)

<?php
$api_key = getenv('JBR_API_KEY');
$base_url = 'https://api.jobbookers.co.uk/v1';

function get_drive_time($from, $to, $api_key, $base_url) {
    $url = $base_url . '/route?' . http_build_query([
        'from' => $from,
        'to'   => $to,
    ]);

    $ch = curl_init($url);
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => [
            'Authorization: Bearer ' . $api_key,
            'Accept: application/json',
        ],
        CURLOPT_TIMEOUT => 10,
    ]);

    $response = curl_exec($ch);
    $status   = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($status !== 200) {
        throw new Exception('API error: ' . $status);
    }

    return json_decode($response, true);
}

// Usage
$result = get_drive_time('NR21 8AB', 'PE37 7JL', $api_key, $base_url);
echo $result['duration_mins'] . ' mins, ' . $result['distance_miles'] . ' miles';