POI Update Web Service
Goal & purpose
The POI Update Web Service allows you to sync (add/replace/remove) your POIs with the RouteYou-platform any time you think this is needed. Ones the POIs area available on the RouteYou platform you can see them on the RouteYou platform and you can make use of all the tools linked to POIs on the RouteYou-platform.
To check the status of your POIs, do the following:
- Log in
- Select the tab "My Places of Interest" - zoom and pan to see the POIs
Remark: The POI Update Web Service is a RouteYou+ service. Please contact sales[at-r.] if you want to make use of this service and you don't have yet an agreement with RouteYou.
Process
Overview
There are three steps to sync your POIs
- You log in via the Authentication Web Service (you need a KEY to do this - if you don't have one, contact info@routeyou.com)
- You add your sync-job(s) to the RouteYou Job Web Servive
- You can check the status/result of that job. If positive, your POI info is now synced with the RouteYou POI-DB.
Important to understand is that the POIs along your routes (8 on the figure below)) are not updated automatically, because the routes contain a copied version of the POIs in the POI-DB (1), triggered via the POI-PUSH (5, see figure below).
Add method
To manage your set of pois you have to invoke the method add from the Job Web Service. For more information read the documentation of the Job Web Service. Within this job you can add, update and delete pois that you own. You have to be logged in when submitting the set of pois. Read here how to do this. All the created/updated pois will be linked to the account of the logged in user.
Parameters needed for invoking add
- actionId: 60
- input: an array containing the poi records. The poi-format is explained below.
Poi-format
Fields and meaning
We defined a simple flat-table structure to transfer the data of your POIs, in JSON-RPC format.
Important: The character encoding of all fields must be UTF-8.
The mandatory fields for the save-action are:
- action
- language
- location_name
- location_coord_x
- location_coord_y
- text
All other fields may be omitted or left blank.
The mandatory fields for the delete-action are:
- action
- reference_id1
Fields:
- action: defines what the to with the record. Possible actions are save/delete
- language: 2 character language code (ISO 639-1 language code). Examples: en (English), nl (Dutch), fr (French), ...
- reference_id1: this is the id used by your organisation. When omitted, it is not possible to delete/update existing locations on RouteYou.
- reference_id2: this is the sub id used by your organisation.
- location_name: name of the location
- location_type_id: id of the location type. See the overview of the location types and their id's here. When the location type is omitted or not known the default type 'poi' will be used.
- location_coord_x: WGS_84, decimal
- location_coord_y: WGS_84, decimal
- location_address_street: street of the adress
- location_address_number: house number of the adress
- location_address_postbox: postbox of the address
- location_address_city: city of the address
- location_address_zipcode: zipcode
- location_address_state: state of the address
- location_address_country: country of the address
- location_themes: array of theme IDS
- location_characteristics: array of characteristics IDS
- text: text description
- text_permission: defines the accessibility of the text. Possible permissions are public/private. Most likely, you want to make it public.
- text_source_name: name of the source of the text
- text_source_url: url of the source of the text (has to start with "http://" or "https://" )
- text_copyright_id: Possible id's:
- 2: "Internal only"
- 3: "Problem"
- 5: "GNU"
- 6: "CC 1.2"
- 7: "CC 2.0"
- 8: "All rights reserved"
- 9: "CC 2.5"
- Remark: If you need an extra one, please contact us
- text_info_url: url with more info about the text (has to start with "http://" or "https://" )
- media_url: link to the media file (has to start with "http://" or "https://" )
- media_type: Possible types are image, Vimeo
(, Youtube) - media_source_name: name of the source of the media
- media_source_url: url of the source of the media (has to start with "http://" or "https://" )
- media_copyright_id: Possible id's:
- 2: "Internal only"
- 3: "Problem"
- 5: "GNU"
- 6: "CC 1.2"
- 7: "CC 2.0"
- 8: "All rights reserved"
- 9: "CC 2.5"
- icon_theme: defines the theme of the used icons for this poi. Supported values are 'gray', 'red', 'orange', 'yellow', 'green', 'cyan', 'blue', 'purple', 'magenta', 'pink'
Example in JSON-RPC
The following code will upload a poi dataset to the RouteYou system.
// Simply provide the class with your key, the token will be generated automatically.
RouteYou_Json_Client::setKey('<key>');
// Log in.
$userService = new RouteYou_Json_Client('User', '2.0');
$userInfo = $userService->logInWithEmail('<email>', '<password>');
// Construct poi-data. Add a poi in English and Dutch and then remove the English version.
$poiRecords = array();
$poiRecord[] = array(
'action' => 'save',
'reference_id1' => 'rty_1',
'language' => 'en',
'location_name' => 'RouteYou office',
'location_type_id' => 78,
'text' => 'Example text of the RouteYou poi',
'location_themes' => array(1,2)
);
$poiRecord[] = array(
'action' => 'save',
'reference_id1' => 'rty_1',
'language' => 'nl',
'location_name' => 'RouteYou kantoor',
'location_type_id' => 78,
'text' => 'Voorbeeld tekst van de RouteYou poi',
'location_characteristics' => array(1,2)
);
$poiRecord[] = array(
'action' => 'delete',
'reference_id1' => 'rty_1',
'language' => 'en' //When the language is omitted , all translations will be deleted
);
// Add a job to process a POI. If successful the field
// $result contains the job-id.
$jobService = new RouteYou_Json_Client('Job', '2.0');
$result = $jobService->add(60, $poiRecords);
// Get the job-information. When the job is processed,
// the field output in $jobInfo contains the route-id
$jobInfo = $jobService->getSummary($result['id']);
How to get feed-back
// Get the job-information. When the job is processed, // the field output in $jobInfo contains the route-id $jobInfo = $jobService->getSummary($result['id']);
You get back an array with info about your sync action.
array(
array(
"Status" =>Succesfull/Failed,
"Errormessage" =>43.764875
)
)
Specific cases
Type does not exist
When the location type is omitted or not known the default type 'poi' will be used.
Multiple types for locations/POIs
You might have a have a multiple type model for POIs or locations: example: a hotel is also a restaurantant and a tourist information point.
In that case, you have to repeat the records with a new type.
Your reference_id will be the same in those case, but on RouteYou we will make 2 ore more locations for this, since a location is only allowed one type in our model.
Multiple languages
See above in example
Multiple pictures
See above in example
Multiple video's
See above in example