Description
Natural.Healthcare WP Widget Phase 1Overview
I need to have a WordPress widget that will be deployable via the standard https://WordPress.org/plugins/ directory. This plugin will live in the ‘widgets’ section of the menu so that it can be easily dragged in to a WordPress widget area.
The purpose of this widget will be similar to google’s adsense plugin, but instead of showing search engine ads, we’ll be displaying listings for naturopathic doctors that are near the user based on their IP address. The listing will be obtained through a single API call that includes the IP address of the client, and the settings set by the user, that I’ll cover shortly. The results will be used to construct the widget contents.
API
Listing Lookup – (Settings Screen)
If the WordPress Admin has a listing on [http://natural.healthcare](http://natural.healthcare/), they may choose to exclude search results that are near their own office to avoid competition. To do this, we will need to determine the location of their office. The user can search for their listing using an autocomplete-style search using this request:
“`
curl -X “GET” “https://api.natural.healthcare/v1/listings/autocomplete?fields[]=listing_id,url,lat,lon,name&q=[QUERY]”
200
[
{
“name”: “name”,
“listing_id”: “listing_id”,
“url”: “listing_url”,
“lat”: “lat”,
“lon”: “lon”
},
{
“name”: “name”,
“listing_id”: “listing_id”,
“url”: “listing_url”,
“lat”: “lat”,
“lon”: “lon”
}
]
“`
QUERY
This will be the text the user has typed in so far. The search can be triggered after 3 characters. The results, as you can see, will include the lat(itude), lon(gitude), listing_id, and url. These values must be saved in WordPress settings.
Listing Display
“`
curl -X “GET” “https://api.natural.healthcare/v1/listings/search?client_ip=IP&exclude_lat=LAT&exclude_lon=LON&exclude_rad=RADIUS&owner_id=LISTING_ID&req_id=REQ_ID&referrer=REFERRER&max_listings=MAX_LISTINGS”
# Successful Response: 200
{
“location”: “City, State we located”,
“listings”:[
{
“image”: “img_url”,
“url”: “https://www.natural.healthcare/PATH_TO_LISTING?request_id=req_id”,
“title”: “Name of location”,
“distance”: “distance in mi”
},
{
“image”: “img_url”,
“url”: “https://www.natural.healthcare/PATH_TO_LISTING?request_id=req_id”,
“title”: “Name of location”,
“distance”: “distance in mi”
}
]
}
# Failed Response: 400
{
“error”: “something went wrong”,
“cause”: “the problem with the request, which should include info about how the request was malformed”
}
“`
Parameters
- IP – The IP address from the request to the WordPress site. This value must respect X-Forwarded-For type headers as necessary to avoid yielding the IP address of a front-end proxy
- LAT,LON,LISTING_ID – These are all fields that are loaded from the settings screen. They are optional.
- REQ_ID – The request id is a [uniq_id](http://php.net/manual/en/function.uniqid.php) that you will generate for each request to the API. You will notice that it is appended to the urls that are returned by the api. It’s purpose is to help me correlate click-rates, and mitigate potential fraud
- REFERRER – The [permalink](https://developer.WordPress.org/reference/functions/get_permalink/) of the page being loaded. (This will need to be encoded). This value will also be used so that I can determine which pages are providing the most traffic.
- MAX_LISTINGS – This value comes from the settings, and determines the maximum number of listings that can be returned
Implementation
Server Side Calls
The api calls need to be performed server side, because I want to obtain backlinks from this, and google is wise to javascript embeds that render resources from external sources. So I want the call to be made server side. As I understand it, php has a requests module that can make the call asynchronously
Caching
We will not be caching any of these requests at any level, because I can not measure the effectiveness of placements from a website if I don’t know how often they’re displaying the widget. I can’t compensate them for its use if I don’t have accurate numbers here either. A more complicated solution might eventually be warranted, but not yet.
Screens
There will be two screens. The widget itself, and a settings screen. I have balsamiq mockups for these, but can’t include them in this post.
Qualifications
I’m not a WordPress developer, but I am a software developer in a lot of other languages. I will have high standards for code quality, unit testing, and source control usage.