# Beam API Examples
Here's some practical examples to get you up and running with your Beacon Beam (API)
# 🔭 Example Beam
If you'd just like to see what a Beam looks like within the Project Beacon app, you can add the Beam below!
# Example JSON Format
{
"success": "1",
"css": "<style>.beam__property-header{padding:15px 25px}.beam__property-card{max-width:450px;width:85%;display:block;margin:0 auto;margin-bottom:35px;background-color:#fff;border:1px solid #e8e8e8;border-radius:20px;box-shadow:2px 2px 22px 2px rgba(0,0,0,.1);overflow:hidden}.beam__property-image img{max-width:100%;width:100%}.beam__property-body{padding:15px 25px}.beam__property-text{margin:0;margin-bottom:8px;padding:0;font-family:sans-serif;font-weight:400;font-size:16px;line-height:1.5;color:#bfbfbf}.beam__property-text-secondary{font-size:12px;font-weight:300;color:#7b7b7b}.beam__property-text-main{font-size:20px;font-weight:700;color:#757575}.beam__property-text-main.beam__property-text-main-title{font-weight:300;font-size:26px}</style>",
"js": "",
"notification": "Properties Found: 11",
"lenders": [
{
"name": "Summary",
"names": "<div class=\"beam__property-header\">\n <h1 class=\"beam__property-text beam__property-text-main beam__property-text-main-title\">Summary</h1>\n </div><div class=\"beam__property-card\">\n <div class=\"beam__property-body\">\n <h4 class=\"beam__property-text beam__property-text-secondary\">Properties</h4>\n <h3 class=\"beam__property-text beam__property-text-main\">11</h3>\n </div>\n </div>"
},
{
"name": "Properties",
"names": "<div class=\"beam__property-header\">\n <h1 class=\"beam__property-text beam__property-text-main beam__property-text-main-title\">Properties</h1>\n </div><div class=\"beam__property-card\">\n <div class=\"beam__property-image\">\n <img style=\"width:100%;\" src=\"https://mr0.homeflow-assets.co.uk/files/photo/image/17412/2390/470x314/BND3040901.jpg\" alt=\"Ewenny Road, Ewenny, Bridgend\"/>\n </div>\n <div class=\"beam__property-body\">\n <h4 class=\"beam__property-text beam__property-text-secondary\">Ewenny Road, Ewenny, Bridgend</h4>\n <h3 class=\"beam__property-text beam__property-text-main\">4 bedrooms £700,000\n Freehold</h3>\n <p class=\"beam__property-text\">\n 4 double bedroom Modern Queen Anne style family residence in the sought after location of Ewenny, Bridgend....\n </p>\n </div>\n </div><div class=\"beam__property-card\">\n <div class=\"beam__property-image\">\n <img style=\"width:100%;\" src=\"https://mr2.homeflow-assets.co.uk/files/photo/image/16658/8963/470x314/BND3031852.jpg\" alt=\"Coychurch Road, Bridgend\"/>\n </div>\n <div class=\"beam__property-body\">\n <h4 class=\"beam__property-text beam__property-text-secondary\">Coychurch Road, Bridgend</h4>\n <h3 class=\"beam__property-text beam__property-text-main\">8 bedrooms £498,000\n Freehold</h3>\n <p class=\"beam__property-text\">\n A beautiful 8 Bedroom family residence over 3 floors boasting spacious accommodation throughout and situate...\n </p>\n </div>\n </div><div class=\"beam__property-card\">\n <div class=\"beam__property-image\">\n <img style=\"width:100%;\" src=\"https://mr0.homeflow-assets.co.uk/files/photo/image/17436/6476/470x314/BND3004971.jpg\" alt=\"Nant Y Coed Close, Heol-y-Cyw, BRIDGEND\"/>\n </div>\n <div class=\"beam__property-body\">\n <h4 class=\"beam__property-text beam__property-text-secondary\">Nant Y Coed Close, Heol-y-Cyw, BRIDGEND</h4>\n <h3 class=\"beam__property-text beam__property-text-main\">5 bedrooms £425,000\n Freehold</h3>\n <p class=\"beam__property-text\">\n Nant Y Coed Close is a small private cul de sac comprising high quality executive style properties of simil...\n </p>\n </div>\n </div><div class=\"beam__property-card\">\n <div class=\"beam__property-image\">\n <img style=\"width:100%;\" src=\"https://mr0.homeflow-assets.co.uk/files/photo/image/17676/2085/470x314/BND3041073.jpg\" alt=\"Andrews Close, Tondu, Bridgend\"/>\n </div>\n <div class=\"beam__property-body\">\n <h4 class=\"beam__property-text beam__property-text-secondary\">Andrews Close, Tondu, Bridgend</h4>\n <h3 class=\"beam__property-text beam__property-text-main\">6 bedrooms Offers over £325,000\n Freehold</h3>\n <p class=\"beam__property-text\">\n Peter Alan Bridgend are pleased to present this six bedroom detached property offered for sale in Tondu, Bridgend. This spacious family home benefits from four piece family bathroom, conservatory, utility room and garage. Viewing is highly recommended call 01656 657201.\n </p>\n </div>\n </div><div class=\"beam__property-card\">\n <div class=\"beam__property-image\">\n <img style=\"width:100%;\" src=\"https://mr0.homeflow-assets.co.uk/files/photo/image/16800/4455/470x314/BND3028482.jpg\" alt=\"Stormy Lane, Nantymoel, Bridgend\"/>\n </div>\n <div class=\"beam__property-body\">\n <h4 class=\"beam__property-text beam__property-text-secondary\">Stormy Lane, Nantymoel, Bridgend</h4>\n <h3 class=\"beam__property-text beam__property-text-main\">5 bedrooms £325,000\n Freehold</h3>\n <p class=\"beam__property-text\">\n Brook Cottage is a spacious five bedroom detached property set in the picturesque mountains of Nantymoel. T...\n </p>\n </div>\n </div><div class=\"beam__property-card\">\n <div class=\"beam__property-image\">\n <img style=\"width:100%;\" src=\"https://mr1.homeflow-assets.co.uk/files/photo/image/16853/6439/470x314/BND30361213.jpg\" alt=\"Merthyr Mawr Road, Bridgend\"/>\n </div>\n <div class=\"beam__property-body\">\n <h4 class=\"beam__property-text beam__property-text-secondary\">Merthyr Mawr Road, Bridgend</h4>\n <h3 class=\"beam__property-text beam__property-text-main\">5 bedrooms Offers over £300,000\n Freehold</h3>\n <p class=\"beam__property-text\">\n Peter Alan are pleased to offe this beautifully presented, spacious property. This characterful semi detached property is situated on the sought after Merthyr Mawr Road with close access to all town centre amenities, the M4 and A48. Don't miss the opportunity to view this stunning and unusual home.\n </p>\n </div>\n </div><div class=\"beam__property-card\">\n <div class=\"beam__property-image\">\n <img style=\"width:100%;\" src=\"https://mr1.homeflow-assets.co.uk/files/photo/image/17213/8433/470x314/BND30402210.jpg\" alt=\"Clos Pwll Clai, Tondu, Bridgend\"/>\n </div>\n <div class=\"beam__property-body\">\n <h4 class=\"beam__property-text beam__property-text-secondary\">Clos Pwll Clai, Tondu, Bridgend</h4>\n <h3 class=\"beam__property-text beam__property-text-main\">3 bedrooms £245,000\n Freehold</h3>\n <p class=\"beam__property-text\">\n New to the market, this three bedroom detached property offered for sale in Tondu, Bridgend, would make a great family home and benefits from garage, en-suite and enclosed rear garden. Viewing is recommended to appreciate this well presented home. Call Peter Alan on 01656 657201.\n </p>\n </div>\n </div><div class=\"beam__property-card\">\n <div class=\"beam__property-image\">\n <img style=\"width:100%;\" src=\"https://mr3.homeflow-assets.co.uk/files/photo/image/16987/3858/470x314/BND30381214.jpg\" alt=\"Ffordd Y Parc, Bridgend\"/>\n </div>\n <div class=\"beam__property-body\">\n <h4 class=\"beam__property-text beam__property-text-secondary\">Ffordd Y Parc, Bridgend</h4>\n <h3 class=\"beam__property-text beam__property-text-main\">4 bedrooms OIEO £238,500\n Freehold</h3>\n <p class=\"beam__property-text\">\n A well presented four bedroom detached property situated in the sought after area of Litchard. The property is within close proximity to local schools, shops that include the McArthur Glen Outlet, the M4, and The Princess of Wales Hospital. Viewing is Highly Recommended!!\n </p>\n </div>\n </div><div class=\"beam__property-card\">\n <div class=\"beam__property-image\">\n <img style=\"width:100%;\" src=\"https://mr0.homeflow-assets.co.uk/files/photo/image/17012/3504/470x314/BND30389714.jpg\" alt=\"Oaklands Road, Bridgend\"/>\n </div>\n <div class=\"beam__property-body\">\n <h4 class=\"beam__property-text beam__property-text-secondary\">Oaklands Road, Bridgend</h4>\n <h3 class=\"beam__property-text beam__property-text-main\">3 bedrooms £238,000\n Freehold</h3>\n <p class=\"beam__property-text\">\n Viewing is Highly Recommended! We offer this deceptively spacious three bedroom semi detached with an annex to side offered for sale with no on going chain. The property is situated within close proximity to local schools, shops and other amenities that include Newbridge Fields.\n </p>\n </div>\n </div><div class=\"beam__property-card\">\n <div class=\"beam__property-image\">\n <img style=\"width:100%;\" src=\"https://mr2.homeflow-assets.co.uk/files/photo/image/17130/0811/470x314/BND3039907.jpg\" alt=\"Coed-Y-Cadno, Pen-Y-Fai, Bridgend\"/>\n </div>\n <div class=\"beam__property-body\">\n <h4 class=\"beam__property-text beam__property-text-secondary\">Coed-Y-Cadno, Pen-Y-Fai, Bridgend</h4>\n <h3 class=\"beam__property-text beam__property-text-main\">3 bedrooms Offers over £235,000\n Freehold</h3>\n <p class=\"beam__property-text\">\n Viweing is Highly Recommended on this three bedroom detached property offered for sale in the sought after location of Pen Y Fai, Bridgend. The property benefits from driveway, garage, cloakroom and master bedroom with en-suite shower room. Call us on 01656 657201 to arrange your veiwing.\n </p>\n </div>\n </div><div class=\"beam__property-card\">\n <div class=\"beam__property-image\">\n <img style=\"width:100%;\" src=\"https://mr1.homeflow-assets.co.uk/files/photo/image/17249/7747/470x314/BND30402911.jpg\" alt=\"Penprysg Road, Pencoed, Bridgend\"/>\n </div>\n <div class=\"beam__property-body\">\n <h4 class=\"beam__property-text beam__property-text-secondary\">Penprysg Road, Pencoed, Bridgend</h4>\n <h3 class=\"beam__property-text beam__property-text-main\">4 bedrooms Offers over £230,000\n Freehold</h3>\n <p class=\"beam__property-text\">\n Peter Alan are delighted to present this lovely four bedroom end-terraced property,with no ongoing chain. The property is situated in the popular location of Pencoed and enjoys great views, Bridgend and is close to local amenities and the M4 corridor. To book your viewing call 01656 657201.\n </p>\n </div>\n </div>"
}
]
}
# Adding it
The quickest way to get up and running with Beacon is by adding our demo beam to get an idea of what everything looks like!
- Open the Beacon app, and tap the "Add Beam" button.
- Enter the following for the Beam URL:
https://stsonline.github.io/project-beacon-docs/examples/api/demo.json
- Next, tap "Add This Beam", and wait for it to be added, you'll be automatically taken to the home screen where you'll be able to see your Beam:
- Tap on the Beam, or one of it's pages to view your newly added Beam 🌟
# 🏠 Properties API
TIP
We'll be using Express JS in this example. Our example includes a simple scraper, this is for demo purposes only and we advise not to use this in a production environment.
# 1. Setting up the project
In this section, we'll look at creating the project template where you'll be able to set up your API.
# create the api folder
mkdir properties-api && cd properties-api
# init a NPM project to install dependencies
npm init -y
# install dependencies (this may take a while)
npm install --save express body-parser cors request cheerio dotenv
# create a file to contain env variables, and set it up!
touch .env.example && echo "# API server details" >> .env.example && echo "SERVER_PORT=3000" >> .env.example && echo "SERVER_IP=0.0.0.0" >> .env.example && echo "# URL to Scrape" >> .env.example && echo "SCRAPE_URL=https://www.peteralan.co.uk/branches/bridgend/sales/page-1" >> .env.example && cp .env.example .env
# create a file that will be served later!
touch api.js
# 2. Require our dependencies
After setting up the project we need to edit api.js and require our dependencies:
// require dotenv for env
require('dotenv').config()
// require packages
const express = require('express')
const bodyParser = require('body-parser')
const request = require('request')
const cheerio = require('cheerio')
const cors = require('cors')
const app = express()
const port = process.env.SERVER_PORT || 80
const ip = process.env.SERVER_IP || '0.0.0.0'
const url = process.env.SCRAPE_URL
# 3. Let's use some of our dependencies
We now need to enable and use some of our dependencies in our project:
// allow Express JS to run regardless of domain (we can remove CORS if this is going to be restricted to domain)
app.use(cors());
// support json encoded bodies
app.use(bodyParser.json());
// support encoded bodies
app.use(bodyParser.urlencoded({ extended: true }));
# 4. Setup an endpoint & scrape properties
Setup your endpoint that you'd like to use within the Beacon app, ours below will be /api/properties, we're also going to create something quick to scrape and build the response for the Beacon app.
// create an endpoint for demo
app.get('/api/properties', (req, res) => {
// temporarily store markup
var markup = { summary: "", properties: "" }
// build the required API format for Beacon
var beam = {
success: "0",
css: "<style>.beam__property-header{padding:15px 25px}.beam__property-card{max-width:450px;width:85%;display:block;margin:0 auto;margin-bottom:35px;background-color:#fff;border:1px solid #e8e8e8;border-radius:20px;box-shadow:2px 2px 22px 2px rgba(0,0,0,.1);overflow:hidden}.beam__property-image img{max-width:100%;width:100%}.beam__property-body{padding:15px 25px}.beam__property-text{margin:0;margin-bottom:8px;padding:0;font-family:sans-serif;font-weight:400;font-size:16px;line-height:1.5;color:#bfbfbf}.beam__property-text-secondary{font-size:12px;font-weight:300;color:#7b7b7b}.beam__property-text-main{font-size:20px;font-weight:700;color:#757575}.beam__property-text-main.beam__property-text-main-title{font-weight:300;font-size:26px}</style>",
js: "",
notification: "Properties found!",
lenders: [{
name: "Summary",
names: ""
},{
name: "Properties",
names: ""
}]
}
// make the request to website to scrape details
request(url, function (error, response, html) {
if (!error && response.statusCode == 200) {
// define how we're going to use Cheerio, and load the HTML from our response
const $ = cheerio.load(html);
// total properties found
var totalProperties = 0
// set the page titles
markup.summary = `<div class="beam__property-header">
<h1 class="beam__property-text beam__property-text-main beam__property-text-main-title">Summary</h1>
</div>`
// set the page titles
markup.properties = `<div class="beam__property-header">
<h1 class="beam__property-text beam__property-text-main beam__property-text-main-title">Properties</h1>
</div>`
// get each property
$('.searchResults .propertyTeaser').each((i, el) => {
// increment total properties
totalProperties++
// get the individual bits of data
var imgSrc = ''
// check what kind of images we have first
if ($(el).find('.premium-property-photos .propertyTeaser-thumb').length) {
imgSrc = $(el).find('.premium-property-photos .propertyTeaser-thumb').first().attr('src')
} else {
imgSrc = $(el).find('.propertyTeaser-mainPhoto .propertyTeaser-thumb').attr('src')
}
// get individual bits of info
const address = $(el).find('.propertyTeaser-address').text().trim()
const beds = $(el).find('.propertyTeaser-bedrooms').text().trim()
const price = $(el).find('.propertyTeaser-price').text().trim()
const desc = $(el).find('.propertyTeaser-description').text().trim()
// create the markup for the property cards to display on the properties page
markup.properties += `<div class="beam__property-card">
<div class="beam__property-image">
<img style="width:100%;" src="https:${(imgSrc != '' && imgSrc != null) ? imgSrc : '//via.placeholder.com/450x220'}" alt="${address}"/>
</div>
<div class="beam__property-body">
<h4 class="beam__property-text beam__property-text-secondary">${address}</h4>
<h3 class="beam__property-text beam__property-text-main">${beds} ${price}</h3>
<p class="beam__property-text">
${desc}
</p>
</div>
</div>`
})
// properties found
markup.summary += `<div class="beam__property-card">
<div class="beam__property-body">
<h4 class="beam__property-text beam__property-text-secondary">Properties</h4>
<h3 class="beam__property-text beam__property-text-main">${totalProperties}</h3>
</div>
</div>`
// successful
beam.success = "1"
// update the notification (this could be a real-time metric)
beam.notification = `Properties Found: ${(totalProperties > 0) ? totalProperties : 0}`
// put summary onto first page
beam.lenders[0].names = markup.summary
// put properties into the second page
beam.lenders[1].names = markup.properties
// expose the API data on the API to use within Beacon
res.status(200).send(beam)
}
});
})
# 5. Expose the API endpoint
Now we've got our API endpoint set up, we can expose its endpoint when we start the API:
// open the API on the following IP, and Port
app.listen(port, ip, () => console.log(`API running on http:/${ip}:${port}!`))
# Launch the API!
We're all ready to start the API!
# start the API
node api.js
Want the full source code? See: here
TIP
To access your API within the Beacon app, we recommend getting ngrok installed and set up, after which you can launch ngrok http 3000