JavaScript Maps SDK

Custom Places

Contents

The Custom Places service provides ten different functions for creating, editing, and deleting custom places, sets, and categories.

CustomPlace Sets

Sets allow you to put as few or as many CustomPlace objects as you want into a single group.

Add New Set

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) {}
});

Update Existing Set

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) {}
});

Delete Existing Set

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) {}
});

CustomPlace Categories

Categories provide an another option for organizing your custom places, and allow you to further refine search results during the retrieval process.

Add New Category

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);
  }
});

Update Existing Category

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);
    }
});

CustomPlaces

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.

Get Existing CustomPlaces

Existing CustomPlaces can be retrieved using the ALKMaps.Services.getCustomPlaces function. The parameters are laid out in the table below.

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
             }, ...
         ]
     }, ...
]

Add New CustomPlace

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 laid out in the table below, and the success and failure callback functions. 

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) {}
});

Update Existing CustomPlace

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 updatable 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) {}
});

Delete Existing Custom Place

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) {}
});
Last updated October 4, 2022.
Contents