WRLD POI API for managing POIs within wrld-example-app
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
images
README.md

README.md

WRLD

WRLD POI REST API v1.1.0

This document describes version 1.1.0 of the WRLD POI REST API for submitting and managing custom Points of Interest. The POI API is primarily intended for use with wrld-example-app.


Quick Start

  1. Obtain a Developer Authentication Token by signing up at https://www.wrld3d.com/developers/
  2. Create an Application API Key at https://www.wrld3d.com/developers/
  3. Create a new POI Set
  4. Associate your Application API Key with your newly created POI Set
  5. Add POIs to your POI Set
  6. Perform Free-Text, Category or Indoor queries

Full POI API Specification

Authentication Token

Obtain a Developer Authentication Token by signing up at https://www.wrld3d.com/developers/. The Developer Authentication Token allows you to make authenticated requests against the POI service.

The Authentication Token will be referred to as dev_auth_token throughout this README

Application API Key

The Application API Key is the API key used to authenticate the WRLD SDK. Application Keys can be associated with POI sets, providing that application access to the POI set. Obtain Application API keys from https://www.wrld3d.com/developers/.

Application API Keys will be referred to as app_api_key throughout this README

POI Sets

A POI Set is a collection of Points of Interest. You can associate multiple Application API keys with POI Sets, allowing multiple applications or platforms access to the same POI Set.

A POI Set is a JSON object with the following attributes:

Field Type Description
id integer a unique identifier for the poi set, this is generated for you
name string an appropriate name for the poi set
api_key_permissions string list app api keys that have access to this poi set
Create a POI Set

To create a new POI Set, make a RESTful request passing the name of the POI set:

$ curl -v -XPOST https://poi.wrld3d.com/v1.1/poisets/?token=dev_auth_token -d '{"name":"my-poi-set"}'

The response will be a JSON object specifying the newly created POI Set:

{
"id":1, 
"name":"my-poi-set", 
"api_key_permissions":[]
}

Make note of the POI Set ID, in this case 1 as this is used to make future requests against this newly created POI Set.

Query all POI sets

All POI Sets you own can be listed by making a RESTful request to the poisets resource:

$ curl -v https://poi.wrld3d.com/v1.1/poisets/?token=<dev_auth_token>

This will return a collection of all POI Sets you own

Query a POI set

To query an individual POI Set, make a RESTful request to the poiset:

$ curl -v https://poi.wrld3d.com/v1.1/poisets/<SID>?token=<dev_auth_token>

Where <SID> is the POI Set ID to query. This will return the POI Set as JSON.

Delete a POI Set

To delete a POI Set, make a RESTful request to the poiset:

$ curl -v -XDELETE https://poi.wrld3d.com/v1.1/poisets/<SID>?token=<dev_auth_token>

Where <SID> is the POI Set ID to delete.

Associate App API Key

Application API Keys can be associated with a POI Set to provide that Application access to the POIs in the POI Set.

To do this, make a RESTful call:

$ curl -v -XPOST https://poi.wrld3d.com/v1.1/poisets/<SID>?token=<dev_auth_token> -d '{"apikey":"<app_api_key>"}'

Where app_api_key is the Application API Key, and where <SID> is the POI Set ID to add the Application API Key to.

Unassociate App API Key

To unassociate an Application API Key from a POI Set, perform the following RESTful call:

$ curl -v -XDELETE https://poi.wrld3d.com/v1.1/poisets/<SID>/<app_api_key>?token=<dev_auth_token>

Where app_api_key is the Application API Key, and where <SID> is the POI Set ID to remove the Application API Key from.


Points of Interest

POI

A POI is a Point of Interest. POIs are added to POI Sets and can be searched by applications with access to that POI Set.

The default POI and default taxonomy is supported by wrld-example-app - however both the POI API and wrld-example-app can be customised, so if the default behaviour does not meet your needs you can change the behaviour to suit.

A POI is a JSON object with the following attributes:

Field Required Empty Type Description
id generated no integer a unique identifier for the poi, this is generated for you
title required no string an appropriate title for the poi (i.e. place name)
subtitle required yes string an appropriate subtitle for the poi (i.e. address)
tags required no string a whitespace separated list of tags
lat required no decimal wgs84 decimal degrees latitude
lon required no decimal wgs84 decimal degrees longitude
height_offset optional no decimal height in metres of poi above ground level (default: 0)
indoor optional no boolean whether poi is indoor (default: false)
indoor_id optional yes string the id of the indoor map the poi belongs to (default: empty)
floor_id optional no integer the floor_id of the indoor map the poi belongs to (default: 0)
user_data optional yes json a json object of custom user data (default: empty)

The user_data attribute is entirely custom, however in wrld-example-app the following default user_data attributes are supported:

Field Type Description
image_url string a url to an image to display for the poi
phone string a phone number for the poi
web string a website for the poi
description string a description for the poi
highlight string id of the highlight to enable for a poi
highlight_color array highlight color defined as an [R,G,B,A] int array (0-255)
entity_highlight array string array of entities to highlight for poi
entity_highlight_color array entity highlight color defined as [R,G,B,A] int array (0-255)
custom_view string a url of a html view
custom_view_height int define the height of the custom_view (optional)
Create a new outdoor POI

To create a new POI, make the following RESTful call:

$ curl -v -XPOST https://poi.wrld3d.com/v1.1/poisets/<SID>/pois/?token=<dev_auth_token> -d '{
  "title":"WRLD Dundee",
  "subtitle":"Suite 2, Westport House",
  "tags":"office business",
  "lat":56.459937,
  "lon":-2.978124
}'

Where <SID> is the POI Set ID to add the POI to.

Update an existing POI

To update attributes of an existing POI, make the following RESTful call:

$ curl -v -XPUT https://poi.wrld3d.com/v1.1/poisets/<SID>/pois/<PID>?token=<dev_auth_token> -d '{
  "title":"A new Title",
  "subtitle":"A new Subtitle"
}'

Where <SID> is the POI Set ID the POI belongs to, and <PID> is the ID of the POI

Deleting POIs

To delete an existing POIs in a POI set, make the following RESTful call:

$ curl -v -XDELETE https://poi.wrld3d.com/v1.1/poisets/<SID>/pois/PID?token=<dev_auth_token>

Where <SID> is the POI Set ID the POI belongs to, and <PID> is the ID of the POI

To delete all POIs in a POI set, make the following RESTful call:

$ curl -v -XDELETE https://poi.wrld3d.com/v1.1/poisets/<SID>/pois/?token=<dev_auth_token>

Where <SID> is the POI Set ID the POIs belong to.

Querying POIs

To query POIs in a POI set, make the following RESTful calls:

$ curl -v https://poi.wrld3d.com/v1.1/poisets/<SID>/pois/?token=<dev_auth_token>
$ curl -v https://poi.wrld3d.com/v1.1/poisets/<SID>/pois/PID?token=<dev_auth_token>

Where <SID> is the POI Set ID the POIs belong to, and <PID> is the ID of the POI

Indoor POI

Indoor POIs are supported by default in wrld-example-app. To create an indoor POI three optional attributes must be defined when creating the POI:

Field Type Description
indoor boolean whether poi is indoor (default: false)
indoor_id string the id of the indoor map the poi belongs to (default: empty)
floor_id integer the floor_id of the indoor map the poi belongs to (default: 0)

The indoor_id is the id of the indoor map. See wrld-indoor-maps-api for more details.

Create a new indoor POI

To create a new POI, make the following RESTful call:

$ curl -v -XPOST https://poi.wrld3d.com/v1.1/poisets/<SID>/pois/?token=<dev_auth_token> -d '{
  "title":"Primark",
  "subtitle":"Overgate",
  "tags":"clothing shopping",
  "lat":56.460189,
  "lon":-2.971023,
  "indoor":true,
  "indoor_id":"overgate_dundee",
  "floor_id":0
}'

Where <SID> is the POI Set ID to add the POI to.

Tags

The tags property of a POI is flexible. You can define your own taxonomy and categorisation to suit your need. However, the tags field in the POI must fulfil the following requirements:

  1. All tags must be separated by one whitespace. Eg: "services office business"
  2. Each tag may only contain lowercase alpha characters and/or underscore if required. Numbers are not allowed. Eg: "restaurant bar food_drink"
  3. Tags are ordered from the most specific first to least specific. Eg: "burgers restaurant bar food_drink", therefore that particular POI is best described as a burger joint and least described by food_drink, even though all the tags are relevant to the POI

Default Tags

A default set of high level tags is provided in wrld-example-app. The categories supported are:

Category Tags
Shopping fashion, fashion_kids, fashion_men, fashion_women, florist, groceries, night_shopping, technology
Transport airport, bus, charge_point,cycling, ferry, fuel, limo, parking, subway, taxi, train, tram, transport, uber
Indoor Entertainment art, casino, cinema, gallery, library, music, shopping, spa
Outdoor Entertainment camping, fishing, football, golf, historic_monument, observation_point, park, playing_field, race_track, sailing, shooting, skiing, sports_field, sports, zoo
Accommodation accommodation, lodge, home, home_apartment, hostel, hotel
Landscape Feature forest, lake, mountain, river
Religion christianity, church, islam, judaism, place_of_worship
Bathrooms bathroom, toilet_ladies, toilet_men
Food & Drink bed_breakfast, beer, burgers, chinese_thai, cocktail, coffee, donuts, food_drink, indian, pizza, seafood, steak, sushi, vegan, vegetarian, wine
Buildings atm, bank, dentist, farm, fire, hospital, observatory, offices, payphone, pharmacy, police, post_office, telephone_booth, tourist_info, town_hall, traffic_counter, university, vet, wind_turbine
Smart Office badge_reader, bin, bin_full, co_two_detector, collaboration_space, defibrillator, department, electricity_meter, elevator, emergency_exit, escalator, fire_extinguisher, first_aid, gas_meter, hvac_unit, meeting_room, meeting_room_available_soon, meeting_room_available, meeting_room_unavailable, occupancy_sensor, positioning_beacon, printer, reception, security_alarm, smart_post, smoke_detector, stairs, stationery, temperature_sensor, thermostat, video_conference, washing_machine, wi_fi_point, working_group
Smart Home dining_room, driveway, fireplace, fridge, homeware, kitchen, oven
Web click_and_collect, facebook, google_plus, link, twitter, picasa, photo, video, vimeo, virtual_tour, vr_experience, warning, wikipedia, youtube
Other accessible, alert, border, business, childcare, digital_sign, education, entertainment, events, general, health, lifeguard, meter, message, mobile_phone, my_location, person, pin, remote_control, solar_panels, star, ticket

Searching

Free Text Search

To perform free text search, perform the following query:

$ curl -v "https://poi.wrld3d.com/v1.1/search?s=WRLD&lat=56.460189&lon=-2.971023&apikey=<app_api_key>"
$ curl -v "https://poi.wrld3d.com/v1.1/search?s=WRLD&lat=56.460189&lon=-2.971023&r=10&apikey=<app_api_key>"
$ curl -v "https://poi.wrld3d.com/v1.1/search?s=WRLD&lat=56.460189&lon=-2.971023&n=1&apikey=<app_api_key>"

Where <app_api_key> is an Application API Key that has permission to access a POI Set.

Permitted arguments to the query are:

Field Required Type Description
s required string the search term
lat required decimal wgs84 decimal degrees latitude of the query
lon required decimal wgs84 decimal degrees longitude of the query
r optional decimal radius of the search query in metres (default: 1000.0)
n optional integer maximum number of results to return (default: 20)
ms optional decimal minimum 'score' to results. the higher the number the fewer results will be matched (default: 0.0)
indoor_id optional string id of indoor map to filter results by (default: none)
f optional integer the floor number of the origin of the search, starting at 0 for the lowest floor (default: 0)
fs optional integer floor score drop off, i.e. the number of floors to search above and below (default: 15)
Result Ordering and Scoring

Results are ordered by score. Scored is a measure of closeness to the input query. This measurement of this closeness is complex and subject to change. But the following are factors:

  1. Lexical distance from the search query
  2. Distance from the query origin

Tags Search

To perform a tag search, perform the following query (searches for: "office business"):

$ curl -v "https://poi.wrld3d.com/v1.1/tag?t=office%20business&lat=56.460189&lon=-2.971023&apikey=<app_api_key>"

Where <app_api_key> is an Application API Key that has permission to access a POI Set.

Permitted arguments to the query are:

Field Required Type Description
t optional string the tag(s) to search for. If not specified it will return all POIs it finds
lat required decimal wgs84 decimal degrees latitude of the query
lon required decimal wgs84 decimal degrees longitude of the query
r optional decimal radius of the search query in metres (default: 1000.0)
n optional integer maximum number of results to return (default: 20)

Indoor Map constrained Category Search

To perform a category search, constrained to a particular indoor map, perform the following query:

$ curl -v "https://poi.wrld3d.com/v1.1/indoor?i=<indoor_map_id>&t=office%20business&f=3&apikey=<app_api_key>"

Where <app_api_key> is an Application API Key that has permission to access a POI Set and <indoor_map_id> is the indoor map to constrain against.

Permitted arguments to the query are:

Field Required Type Description
i required string the indoor map ID to constrain against
f required integer the floor number of the origin of the search, starting at 0 for the lowest floor
t optional string the tag(s) to search for. If not specified it will returbn all POIs it finds
n optional integer maximum number of results to return (default: 20)
s optional integer floor score drop off, i.e. the number of floors to search above and below (default: 15)
lat optional decimal wgs84 decimal degrees latitude of the query, used to sort results by distance
lon optional decimal wgs84 decimal degrees longitude of the query, used to sort results by distance

Bulk API

It is possible to make Bulk updates to the POI API to reduce round trips. The Bulk API allows create, update and delete operations to be performed against a POI Set.

To use the Bulk API, make queries of the following form:

$ curl -v -XPOST https://poi.wrld3d.com/v1.1/poisets/<SID>/bulk/?token=<dev_auth_token> -d '{
    "create": [{ 
      "title" : "West House", 
      "subtitle" : "2 West Port, Dundee DD1 5EP", 
      "tags" : "bar food_drink",
      "lat" : 56.459336, 
      "lon" : -2.977645,
      "height_offset" : 0.1
    },
    { 
      "title" : "WRLD Dundee", 
      "subtitle" : "Westport House", 
      "tags" : "office business",
      "lat" : 56.459941, 
      "lon" : -2.978211,
      "height_offset" : 0.1,
      "indoor" : true,
      "indoor_id" : "westport_house_interior_id",
      "floor_id" : 3
    }],

    "update": [{ 
      "id" : 1,
      "title" : "West House", 
      "subtitle" : "2 West Port, Dundee DD1 5EP", 
      "tags" : "office business",
      "lat" : 56.459336, 
      "lon" : -2.977645,
      "height_offset" : 0.1
    }],

    "delete": [1,2,3,4,5]
}'

Where <SID> is the POI Set ID to perform the Bulk Operation on.


Disclaimer

This is a stable, semantically versioned API.

WRLD may make changes to the API from time to time but will adhere to Semantic Versioning and provide backward compatible end points for as long as possible.


Contact us

If you have any problems or queries please raise an issue.