Add Places

Contents

POST /places

Adds multiple places to a place set. There is a limit of 50 places per API call.

Each place should contain at least the address or coordinates.

  • If both address and coordinates are passed, both address and coordinates will be saved and the place will be plotted using coordinates.
  • If only address is passed, the address will be used to find out the coordinates. Both address and coordinates are saved and the place is plotted using the coordinates.
  • If only coordinates are passed, only coordinates are saved and the place is plotted using coordinates.

Request

Authorization: bearer {token}

Parameters:

NameDescriptionData Type
SetId(Required) Unique set identifier to associate with the places.
Int

Body:

NameDescriptionData Type
PlaceName(Required) Name of the place

Criteria:
  • Place names need not be unique under the same place set.
  • Place names cannot be null.
  • Place names should support alphanumeric values.
  • Place names cannot exceed 140 characters.
string
ExternalPlaceId(Optional) Unique external place Id
Alphanumeric
Address(Optional, if coords entered) Address of the location (See below)
Complex
Coords(Optional, if address entered) Coordinates of the location (See below)
Complex
Info(Optional) Comments or description about a place
string
Phone(Optional) Phone number of the place
string

Address

DataDescriptionData Type
StreetAddressThe house number and street name
string
CityThe name of the city
string
StateThe two letter state abbreviation
string
PostalCodeThe postal code or zip
string
CountryThe name of the country
string

Coords

DataDescriptionData Type
LatLatitude as a signed decimal with 6 digits to the right of the decimal. (For example, 40.360621)
string
LonLongitude as a signed decimal with 6 digits to the right of the decimal. (For example, -74.599027)
string

Response

DataDescriptionData Type
IdUnique place identifier
Int
ModifiedOnIndicates the last time the place was modified
DateTime

Sample Request

[
  {
    "PlaceName": "Business Location 1",
    "ExternalPlaceId": "CIDBL1",
    "Info": null,
    "Phone": "609-430-3245",
    "Address": {
      "StreetAddress": "457 North Harrison St.",
      "City": "Princeton",
      "State": "NJ",
      "PostalCode": "08852",
      "Country": "US"
    },
    "Coords": {
      "Lat": "40.368635",
      "Lon": "-74.657760"
    }
  },
  {
    "PlaceName": "Business Location 2",
    "ExternalPlaceId": "CIDBL2",
    "Info": null,
    "Phone": "609-430-3245",
    "Address": {
      "StreetAddress": "1 Independence Way",
      "City": "Princeton",
      "State": "NJ",
      "PostalCode": "08852",
      "Country": "US"
    },
    "Coords": {
      "Lat": "40.360621",
      "Lon": "-74.599027"
    }
  }
]

Sample Response

{
  "data": [
    {
      "Id": 10386508,
      "ModifiedOn": "2019-02-26T15:31:08.623+00:00"
    },
    {
      "Id": 10386509,
      "ModifiedOn": "2019-02-26T15:31:08.623+00:00"
    }
  ]
}

Error Codes

MessageDescription
Either Address or Coords is requiredThis error will be thrown when Place does not include either address or coordinates.
Place Name is requiredThis error will be thrown when Place does not include PlaceName.
No matches foundThis error will be thrown when incorrect address is passed.
Cannot find set with supplied idThis error will be thrown when the Placeset id does not belong to the account.
Duplicated external place Id(s) in databaseThis error will be thrown when the ExternalPlaceId is already associated with a different place within the account.
Last updated March 21, 2020.