Beautiful Places API

Endpointhttps://v1.api.beautifulplaces.ai

Get Nearby Scenic POIs

GET

https://v1.api.beautifulplaces.ai

/scenic-nearby/{filter}

Returns the 3 nearest scenic POIs to the search point, sorted by distance.

Get Nearby Scenic POIs › path Parameters

filter

string · enum · required

'all' returns all POIs. 'high-scenic' returns only POIs marked as architecturally or naturally striking.

Enum values:

all

high-scenic

Get Nearby Scenic POIs › query Parameters

lat

number · required

Latitude of the search point (e.g. 51.5893)

lon

number · required

Longitude of the search point (e.g. -0.1441)

version

integer

Optional POI table version override

Get Nearby Scenic POIs › Headers

Authorization

string · required

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Get Nearby Scenic POIs › Responses

Successful response

Count

integer

Number of POIs returned

High_Scenic_Only

boolean

Whether results are filtered to high-scenic only

object[]

GET/scenic-nearby/{filter}

curl --request GET \
  --url 'https://v1.api.beautifulplaces.ai/scenic-nearby/:filter?lat=%3Cnumber%3E&lon=%3Cnumber%3E' \
  --header 'Authorization: <string>'

shell

Example Responses

{
  "Count": 3,
  "High_Scenic_Only": false,
  "Scenic_POIs": [
    {
      "name": "St James Muswell Hill",
      "credits": "© Martin Addison (cc-by-sa/2.0)",
      "high_scenic_architecture": "False",
      "high_scenic_nature": "False",
      "photos": "240890_dd7bdec7.jpg",
      "latitude": "51.5892905",
      "longitude": "-0.1451126",
      "distance_km": 0.07
    }
  ]
}

json

application/json

Get Scenic POIs by UK Area

GET

https://v1.api.beautifulplaces.ai

/scenic-by-area/{type}/{area_code}

Returns scenic POIs within a UK postcode sector or ward code, sorted by scenic score. Returns up to 3 results.

A postcode sector is the outward code plus the first digit of the inward code (e.g., 'SW1A 1' or 'N6 6').

Get Scenic POIs by UK Area › path Parameters

type

string · enum · required

'postcode_sector' for UK postcode sectors (e.g. N66, SW1A1). 'ward_code' for ONS ward codes (e.g. E05013806).

Enum values:

ward_code

postcode_sector

area_code

string · required

The postcode sector (e.g. 'N66') or ward code (e.g. 'E05013806')

Get Scenic POIs by UK Area › query Parameters

version

integer

Optional POI table version override

Get Scenic POIs by UK Area › Headers

Authorization

string · required

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Get Scenic POIs by UK Area › Responses

Successful response

Count

integer

Number of POIs returned

Area_Type

string

The area type used for the query

Area_Code

string

The area code used for the query

UK_Ward

string

Name of the UK ward

object[]

GET/scenic-by-area/{type}/{area_code}

curl --request GET \
  --url https://v1.api.beautifulplaces.ai/scenic-by-area/:type/:area_code \
  --header 'Authorization: <string>'

shell

Example Responses

{
  "Count": 2,
  "Area_Type": "postcode_sector",
  "Area_Code": "N66",
  "UK_Ward": "Highgate",
  "Scenic_POIs": [
    {
      "name": "Highgate Cemetery",
      "credits": "© Oxyman (cc-by-sa/2.0)",
      "high_scenic_architecture": "False",
      "high_scenic_nature": "False",
      "photos": "1586912_16f406c6.jpg",
      "latitude": "51.5669245",
      "longitude": "-0.146848"
    }
  ]
}

json

application/json

Get Images by Spatial Index

GET

https://v1.api.beautifulplaces.ai

/images-by-index/{index_type}/{index_value}

Returns all images within a specified S2 spatial index cell, sorted by scenic score.

Get Images by Spatial Index › path Parameters

index_type

string · enum · required

Type of spatial index: 's2' for S2 cells

Enum values:

index_value

string · required

The spatial index cell identifier

Get Images by Spatial Index › query Parameters

level

integer · required

S2 cell level/resolution (7-11)

version

integer

Optional POI table version override

limit

integer

Maximum number of images to return (default: 15000)

Default: 15000

Get Images by Spatial Index › Headers

Authorization

string · required

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Get Images by Spatial Index › Responses

Successful response

Count

integer

Number of images returned

Index_Type

string

The spatial index type used

Index_Value

string

The spatial index value queried

Level

integer

The index level/resolution

object[]

GET/images-by-index/{index_type}/{index_value}

curl --request GET \
  --url 'https://v1.api.beautifulplaces.ai/images-by-index/:index_type/:index_value?level=%3Cnumber%3E' \
  --header 'Authorization: <string>'

shell

Example Responses

{
  "Count": 5,
  "Index_Type": "s2",
  "Index_Value": "487604c7",
  "Level": 9,
  "Images": [
    {
      "name": "Tower Bridge",
      "credits": "© John Smith (cc-by-sa/2.0)",
      "high_scenic_architecture": "True",
      "high_scenic_nature": "False",
      "photos": "123456_abc123.jpg",
      "latitude": "51.5055",
      "longitude": "-0.0754"
    }
  ]
}

json

application/json

Get Images by UK Area

GET

https://v1.api.beautifulplaces.ai

/images-by-area/{area_type}/{area_code}

Returns all images within a UK postcode sector or ward code, sorted by scenic score.

A postcode sector is the outward code plus the first digit of the inward code (e.g., 'SW1A1' or 'N66').

Get Images by UK Area › path Parameters

area_type

string · enum · required

'postcode_sector' for UK postcode sectors (e.g. N66, SW1A1). 'ward_code' for ONS ward codes (e.g. E05013806).

Enum values:

ward_code

postcode_sector

area_code

string · required

The postcode sector (e.g. 'N66') or ward code (e.g. 'E05013806')

Get Images by UK Area › query Parameters

version

integer

Optional POI table version override

limit

integer

Maximum number of images to return (default: 100)

Default: 100

Get Images by UK Area › Headers

Authorization

string · required

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Get Images by UK Area › Responses

Successful response

Count

integer

Number of images returned

Area_Type

string

The area type used for the query

Area_Code

string

The area code queried

UK_Ward

string

Name of the UK ward

object[]

GET/images-by-area/{area_type}/{area_code}

curl --request GET \
  --url https://v1.api.beautifulplaces.ai/images-by-area/:area_type/:area_code \
  --header 'Authorization: <string>'

shell

Example Responses

{
  "Count": 10,
  "Area_Type": "postcode_sector",
  "Area_Code": "N66",
  "UK_Ward": "Highgate",
  "Images": [
    {
      "name": "Highgate Cemetery",
      "credits": "© Oxyman (cc-by-sa/2.0)",
      "high_scenic_architecture": "False",
      "high_scenic_nature": "False",
      "photos": "1586912_16f406c6.jpg",
      "latitude": "51.5669245",
      "longitude": "-0.146848"
    }
  ]
}

json

application/json

Get Nearby Scenic POIs

GET

https://v1.api.beautifulplaces.ai

/scenic-nearby/{filter}

Returns the 3 nearest scenic POIs to the search point, sorted by distance.

Get Nearby Scenic POIs › path Parameters

filter

string · enum · required

'all' returns all POIs. 'high-scenic' returns only POIs marked as architecturally or naturally striking.

Enum values:

all

high-scenic

Get Nearby Scenic POIs › query Parameters

lat

number · required

Latitude of the search point (e.g. 51.5893)

lon

number · required

Longitude of the search point (e.g. -0.1441)

version

integer

Optional POI table version override

Get Nearby Scenic POIs › Headers

Authorization

string · required

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Get Nearby Scenic POIs › Responses

Successful response

Count

integer

Number of POIs returned

High_Scenic_Only

boolean

Whether results are filtered to high-scenic only

object[]

Get Scenic POIs by UK Area

GET

https://v1.api.beautifulplaces.ai

/scenic-by-area/{type}/{area_code}

Returns scenic POIs within a UK postcode sector or ward code, sorted by scenic score. Returns up to 3 results.

A postcode sector is the outward code plus the first digit of the inward code (e.g., 'SW1A 1' or 'N6 6').

Get Scenic POIs by UK Area › path Parameters

type

string · enum · required

'postcode_sector' for UK postcode sectors (e.g. N66, SW1A1). 'ward_code' for ONS ward codes (e.g. E05013806).

Enum values:

ward_code

postcode_sector

area_code

string · required

The postcode sector (e.g. 'N66') or ward code (e.g. 'E05013806')

Get Scenic POIs by UK Area › query Parameters

version

integer

Optional POI table version override

Get Scenic POIs by UK Area › Headers

Authorization

string · required

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Get Scenic POIs by UK Area › Responses

Successful response

Count

integer

Number of POIs returned

Area_Type

string

The area type used for the query

Area_Code

string

The area code used for the query

UK_Ward

string

Name of the UK ward

object[]

Get Images by Spatial Index

GET

https://v1.api.beautifulplaces.ai

/images-by-index/{index_type}/{index_value}

Returns all images within a specified S2 spatial index cell, sorted by scenic score.

Get Images by Spatial Index › path Parameters

index_type

string · enum · required

Type of spatial index: 's2' for S2 cells

Enum values:

index_value

string · required

The spatial index cell identifier

Get Images by Spatial Index › query Parameters

level

integer · required

S2 cell level/resolution (7-11)

version

integer

Optional POI table version override

limit

integer

Maximum number of images to return (default: 15000)

Default: 15000

Get Images by Spatial Index › Headers

Authorization

string · required

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Get Images by Spatial Index › Responses

Successful response

Count

integer

Number of images returned

Index_Type

string

The spatial index type used

Index_Value

string

The spatial index value queried

Level

integer

The index level/resolution

object[]

Get Images by UK Area

GET

https://v1.api.beautifulplaces.ai

/images-by-area/{area_type}/{area_code}

Returns all images within a UK postcode sector or ward code, sorted by scenic score.

A postcode sector is the outward code plus the first digit of the inward code (e.g., 'SW1A1' or 'N66').

Get Images by UK Area › path Parameters

area_type

string · enum · required

'postcode_sector' for UK postcode sectors (e.g. N66, SW1A1). 'ward_code' for ONS ward codes (e.g. E05013806).

Enum values:

ward_code

postcode_sector

area_code

string · required

The postcode sector (e.g. 'N66') or ward code (e.g. 'E05013806')

Get Images by UK Area › query Parameters

version

integer

Optional POI table version override

limit

integer

Maximum number of images to return (default: 100)

Default: 100

Get Images by UK Area › Headers

Authorization

string · required

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Get Images by UK Area › Responses

Successful response

Count

integer

Number of images returned

Area_Type

string

The area type used for the query

Area_Code

string

The area code queried

UK_Ward

string

Name of the UK ward

object[]