The Custom Places service provides ten different functions for creating, editing, and deleting custom places, sets, and categories.
Sets allow you to put as few or as many CustomPlace objects as you want into a single group.
The ALKMaps.Services.addCustomPlaceSet function can be used to create a new set. Its two primary parameters are name and tag, please note you will be unable to create a set with the same name/tag combination as an existing set. The other two parameters are optional callback functions to be called on service success and failure. If the function is successful, the set ID number will be returned.
ALKMaps.Services.addCustomPlaceSet({
name: 'name',
tag: 'tag',
success: function(resp){},
failure: function(resp){}
});
A CustomPlace set can be updated using the ALKMaps.Services.updateCustomPlaceSet function. The parameters are id the ID number of an existing set, name the new name value you wish to assign to the set, tag the new tag value you wish to assign to the set, and the success and failure callback functions.
ALKMaps.Services.updateCustomPlaceSet({
id: 123,
name: 'nameUpdate',
tag: 'tagUpdate',
success: function(resp){},
failure: function(resp){}
});
A CustomPlace set can be deleted using the ALKMaps.Services.deleteCustomPlaceSet function. The parameters are id the ID number of an existing set, and the success and failure callback functions.
ALKMaps.Services.deleteCustomPlaceSet({
id: 123,
success: function(resp){},
failure: function(resp){}
});
Categories provide an another option for organizing your custom places, and allow you to further refine search results during the retrieval process.
A new category can be added using the ALKMaps.Services.addCustomCategory function. The parameters are categoryToAdd object that contains
name the name of the category, icon the name of the category icon, iconURL the image URL of the category icon, tag the category tag,
and the success and failure callback functions. If the service is successful, the category ID number will be returned.
ALKMaps.Services.addCustomCategory({
"categoryToAdd":{
name: 'category1',
icon: 'iconName',
iconURL: '//www.alk.com/img/alk-logo-icon.png',
tag: 'tag'
},
success: function(resp){
console.log(resp);
},
failure: function(resp){
console.log(resp);
}
});
An existing category can be updated using the ALKMaps.Services.updateCustomCategory function. The parameters are categoryToUpdate object that contains id the ID number of an existing category, name the new name you wish to assign to the category, icon the new icon name you wish to assign to the category, iconURL the new URL of the icon you wish to assign to the category, tag the new tag you wish to assign to the category, and the success and failure callback functions.
ALKMaps.Services.updateCustomCategory({
"categoryToUpdate":{
id: yourId
name: 'category1Updated',
icon: 'iconNameUpdated',
iconURL: '//www.alk.com/img/alk-logo-icon.png',
tag: 'tag'
},
success: function(resp){
console.log(resp);
},
failure: function(resp){
console.log(resp);
}
});
CustomPlace objects allow you to store various custom data for any place you wish. They have the ability to store a phone number, full address, coordinates, region identifier, custom place name, and can be assigned to an existing set and category.
Existing CustomPlaces can be retrieved using the ALKMaps.Services.getCustomPlaces function. The parameters are layed out in the table below.
Parameters |
||
|---|---|---|
| Parameter | Type | Description |
| id | Number |
ID number of an existing set from which the CustomPlaces will be retrieved. If no set ID number is provided, the search will include all sets for that user. |
| tag | String |
Optional tag of a set to refine the search |
| bounds | ALKMaps.Bounds |
Tile bounds limiting search results to custom places within this box. |
| placeName | String |
Refine the results by optional custom place name. |
| catId | Number |
refine the results by optional custom category id. |
| catName | String |
refine the results by optional custom category name. |
ALKMaps.Services.getCustomPlaces({
id: 82,
catId: 61,
bounds: new ALKMaps.Bounds(-80,40,50,-70).transform(new ALKMaps.Projection("EPSG:4326"), map.getProjectionObject()),
success: function(response){}
});
If the service is successful it will return an array of set objects containing the relevant CustomPlaces.
[
{
"SetID":9,
"SetName":"Walmart",
"SetTag":"AccountId:3",
"CustomPlaces":[
{
"Address":
{
"StreetAddress":"1400 W WABANSIA AVE",
"City":"CHICAGO",
"State":"",
"Zip":"60622",
"County":"US",
"Country":null,
"SPLC":null,
"CountryPostalFilter":0,
"AbbreviationFormat":0
},
"Coords":
{
"Lat":"41.913408",
"Lon":"-87.663022"
},
"Region":4,
"Label":null,
"PlaceName":"TACTICA INTERNATIONAL LLC 3",
"PlaceId":185186,
"PlaceType":null,
"Phone":null,
"Category":null
}, ...
]
}, ...
]
A new CustomPlace can be added using the ALKMaps.Services.addCustomPlace function. If successful, the service will return the CustomPlace ID number. The parameters are setId ID number of the existing set to which the CustomPlace will be added into, place an object containing all the custom data as layed out in the table below, and the success and failure callback functions.
place |
||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Property | Type | Description | ||||||||||||||||||
| categoryId | Number |
ID number of an existing category for the CustomPlace to be inserted under. | ||||||||||||||||||
| phone | String |
Optional phone number of the custom place. | ||||||||||||||||||
| address | Object |
|
||||||||||||||||||
| coords | ALKMaps.LonLat |
Longitude and latitude coordinates of the custom place | ||||||||||||||||||
| dataRegion | Number |
Numerical indentifier for geographical region, use 4 for North America.
|
||||||||||||||||||
| placeName | String |
Optional name for the custom place. | ||||||||||||||||||
ALKMaps.Services.addCustomPlace({
setId: 12345,
place:{
categoryId: 54321,
phone : '800-555-5555' ,
address: {
streetAddress: '',
city: '',
state: '',
county: '',
zip: ''
},
coords: new ALKMaps.LonLat(0,0),
dataRegion: 4, // NA
placeName: 'MyCustomPlace'
},
success: function(resp){},
failure: function(resp){}
});
An existing CustomPlace can be updated using the ALKMaps.Services.updateCustomPlace function. All the parameters are the same as the addCustomPlace function plus the addition of customPlaceId the ID number of the existing CustomPlace you wish to update. Any of the fields besides setId, categoryId, and customPlaceId can be updated. Please note that if no value is specified for any updateable field, it will be set to null regardless of previous value.
ALKMaps.Services.updateCustomPlace({
setId: 12345,
place:{
customPlaceId: 111,
categoryId: 54321,
phone : '800-555-5555' ,
address: {
streetAddress: '',
city: '',
state: '',
county: '',
zip: ''
},
coords: new ALKMaps.LonLat(0,0),
dataRegion: 4, // NA
placeName: 'MyCustomPlaceUpdate'
},
success: function(resp){},
failure: function(resp){}
});
A CustomPlace can be deleted using the ALKMaps.Services.deleteCustomPlace function. The parameters are setId the ID number of the set that the custom place is in, placeId the ID number of the CustomPlace, and the success and failure callback functions.
ALKMaps.Services.deleteCustomPlace({
setId: 12345,
placeId: 111,
success: function(resp){},
failure: function(resp){}
});