ActivateAuthenticateAmplify
DashboardSupportDeveloper Blog

Places

A place resource maps geographical coordinates to a known real-world location (a shop, an office, a park, etc.) where a product or Thng may be interacted within. It can be thought of as defining a fixed location, such as a manufacturing warehouse that every product will be manufactured at, as opposed to an incidental location that a Thng may have. As well as physical coordinates, places can contain conventional street address information, but these are not dynamically linked or validated (coordinates entered bear no relation to the address fields specified).

Places can be used to specify a Thng or action location instead of a set of physical coordinates. See the examples below to learn more.

API Status
General Availability:
/places
/places/:placeId

Jump To ↓

PlaceDocument Data Model
Create a Place
Read a Place
Read all Places
Update a Place
Delete a Place
Get All Places Near Origin
Set a Thng's Location to a Place
Set an Action's Location to a Place

PlaceDocument Data Model

.name (string)
    Friendly name of this resource.

.id (string, read-only)
    The ID of this resource.

.description (string)
    Friendly description of this resource.

.type (string)
    Type of this resource. Can be unset with an empty string.

.customFields (CustomFieldsDocument)
    Object of case-sensititve key-value pairs of custom fields 
    associated with the resource.

.tags (array of string)
    Array of string tags associated with this resource.

.identifiers (IdentifiersDocument)
    Various identifiers (EPC, GTIN, etc.) as a JSON object with 
    one or more key-value pairs.

.createdAt (integer, read-only)
    Timestamp when the resource was created.

.updatedAt (integer, read-only)
    Timestamp when the resource was updated.

.position (GeoJSONPointDocument)
    A GeoJSON Point object. The coordinate order is longitude, 
    then latitude.

.icon (string)
    URL to an image representing the place.

.address (AddressDocument)
    An object representing a street address.

.longitude (number)
    The longitude.

.latitude (number)
    The latitude.

.scopes (ScopesDocument)
    Project and user scopes arrays.

.parentPlace (string)
    The ID of the parent place resource. Cannot be the `id` of this place.

{
  "additionalProperties": false,
  "type": "object",
  "description": "An object describing a real physical place with an address.",
  "properties": {
    "name": {
      "type": "string",
      "description": "Friendly name of this resource."
    },
    "id": {
      "type": "string",
      "description": "The ID of this resource.",
      "pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$",
      "readOnly": true
    },
    "description": {
      "type": "string",
      "description": "Friendly description of this resource."
    },
    "type": {
      "type": "string",
      "description": "Type of this resource. Can be unset with an empty string.",
      "maxLength": 256
    },
    "customFields": {
      "type": "object",
      "description": "Object of case-sensititve key-value pairs of custom fields associated with the resource."
    },
    "tags": {
      "type": "array",
      "description": "Array of string tags associated with this resource.",
      "items": {
        "type": "string",
        "maxLength": 60
      }
    },
    "identifiers": {
      "type": "object",
      "description": "Various identifiers (EPC, ISBN, etc.) as a JSON object with one or more key-value pairs."
    },
    "createdAt": {
      "type": "integer",
      "description": "Timestamp when the resource was created.",
      "readOnly": true,
      "minimum": 0
    },
    "updatedAt": {
      "type": "integer",
      "description": "Timestamp when the resource was updated.",
      "readOnly": true,
      "minimum": 0
    },
    "position": {
      "type": "object",
      "description": "A GeoJSON Point object. The coordinate order is longitude, then latitude.",
      "required": ["type", "coordinates"],
      "properties": {
        "type": {
          "type": "string",
          "description": "The type of the point.",
          "enum": ["Point"]
        },
        "coordinates": {
          "type": "array",
          "description": "The point coordinates",
          "items": {
            "type": "number",
            "minimum": -180,
            "maximum": 180
          }
        }
      }
    },
    "icon": {
      "type": "string",
      "description": "URL to an image representing the place."
    },
    "address": {
      "additionalProperties": false,
      "type": "object",
      "description": "An object representing a street address.",
      "properties": {
        "extension": {
          "type": "string",
          "description": "The extension of the address."
        },
        "street": {
          "type": "string",
          "description": "The street of the address."
        },
        "postalCode": {
          "type": "string",
          "description": "The postal code of the address."
        },
        "city": {
          "type": "string",
          "description": "The city of the address."
        },
        "county": {
          "type": "string",
          "description": "The county of the address."
        },
        "state": {
          "type": "string",
          "description": "The state of the address."
        },
        "country": {
          "type": "string",
          "description": "The country of the address."
        },
        "countryCode": {
          "type": "string",
          "description": "The country code of the address."
        },
        "district": {
          "type": "string",
          "description": "The district of the address."
        },
        "buildingName": {
          "type": "string",
          "description": "The building name of the address."
        },
        "buildingFloor": {
          "type": "string",
          "description": "The building floor of the address."
        },
        "buildingRoom": {
          "type": "string",
          "description": "The building room of the address."
        },
        "buildingZone": {
          "type": "string",
          "description": "The building zone of the address."
        },
        "crossing1": {
          "type": "string",
          "description": "The first crossing of the address."
        },
        "crossing2": {
          "type": "string",
          "description": "The second crossing of the address."
        }
      }
    },
    "longitude": {
      "type": "number",
      "description": "The longitude."
    },
    "latitude": {
      "type": "number",
      "description": "The latitude."
    },
    "scopes": {
      "additionalProperties": false,
      "type": "object",
      "description": "Project and user scopes arrays.",
      "properties": {
        "users": {
          "type": "array",
          "description": "An array of Application User IDs this resource is scoped to.",
          "items": { "type": "string" }
        },
        "projects": {
          "type": "array",
          "description": "An array of project IDs this resource is scoped to.",
          "items": {
            "type": "string",
            "description": "The ID of this resource.",
            "pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$",
            "readOnly": true
          }
        }
      }
    },
    "parentPlace": {
      "type": "string",
      "description": "The ID of the parent place resource. Cannot be the `id` of this place.",
      "pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$"
    }
  },
  "x-filterable-fields": ["name", "identifiers", "tags"]
}

{
  "id": "U4w8qhpArDRSkRaRwFRUfnVe",
  "createdAt": 1510918067036,
  "tags": [
    "example",
    "place"
  ],
  "updatedAt": 1510918067036,
  "name": "AS Garments Ltd.",
  "description": "Facility for AS Garments Ltd.",
  "type": "factory",
  "position": {
    "type": "Point",
    "coordinates": [
      5.625,
      21.94304553343818
    ]
  },
  "address": {
    "street": "Float Street",
    "postalCode": "N16FG",
    "city": "London",
    "country": "United Kingdom"
  },
  "identifiers": {
    "gs1:414": "1234567890128"
  },
  "latitude": 21.94304553343818,
  "longitude": 5.625
}

See also: ScopesDocument, AddressDocument

Filterable Fields

This resource type can be filtered using the following fields and operators.

FieldTypeOperators
nameString=
identifiers.<key>String=
tagsList of string=

AddressDocument Data Model

.extension (string)
    The extension of the address.

.street (string)
    The street of the address.

.postalCode (string)
    The postal code of the address.

.city (string)
    The city of the address.

.county (string)
    The county of the address.

.state (string)
    The state of the address.

.country (string)
    The country of the address.

.countryCode (string)
    The country code of the address.

.district (string)
    The district of the address.

.buildingName (string)
    The building name of the address.

.buildingFloor (string)
    The building floor of the address.

.buildingRoom (string)
    The building room of the address.

.buildingZone (string)
    The building zone of the address.

.crossing1 (string)
    The first crossing of the address.

.crossing2 (string)
    The second crossing of the address.

{
  "additionalProperties": false,
  "type": "object",
  "description": "An object describing a real physical place with an address.",
  "properties": {
    "name": {
      "type": "string",
      "description": "Friendly name of this resource."
    },
    "id": {
      "type": "string",
      "description": "The ID of this resource.",
      "pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$",
      "readOnly": true
    },
    "description": {
      "type": "string",
      "description": "Friendly description of this resource."
    },
    "customFields": {
      "type": "object",
      "description": "Object of case-sensititve key-value pairs of custom fields associated with the resource."
    },
    "tags": {
      "type": "array",
      "description": "Array of string tags associated with this resource.",
      "items": {
        "type": "string",
        "maxLength": 60
      }
    },
    "identifiers": {
      "type": "object",
      "description": "Various identifiers (EPC, GTIN, etc.) as a JSON object with one or more key-value pairs."
    },
    "createdAt": {
      "type": "integer",
      "description": "Timestamp when the resource was created.",
      "readOnly": true,
      "minimum": 0
    },
    "updatedAt": {
      "type": "integer",
      "description": "Timestamp when the resource was updated.",
      "readOnly": true,
      "minimum": 0
    },
    "position": {
      "type": "object",
      "description": "A GeoJSON Point object. The coordinate order is longitude, then latitude.",
      "required": ["type", "coordinates"],
      "properties": {
        "type": {
          "type": "string",
          "description": "The type of the point.",
          "enum": ["Point"]
        },
        "coordinates": {
          "type": "array",
          "description": "The point coordinates",
          "items": {
            "type": "number",
            "minimum": -180,
            "maximum": 180
          }
        }
      }
    },
    "icon": {
      "type": "string",
      "description": "URL to an image representing the place."
    },
    "address": {
      "additionalProperties": false,
      "type": "object",
      "description": "An object representing a street address.",
      "properties": {
        "extension": {
          "type": "string",
          "description": "The extension of the address."
        },
        "street": {
          "type": "string",
          "description": "The street of the address."
        },
        "postalCode": {
          "type": "string",
          "description": "The postal code of the address."
        },
        "city": {
          "type": "string",
          "description": "The city of the address."
        },
        "county": {
          "type": "string",
          "description": "The county of the address."
        },
        "state": {
          "type": "string",
          "description": "The state of the address."
        },
        "country": {
          "type": "string",
          "description": "The country of the address."
        },
        "countryCode": {
          "type": "string",
          "description": "The country code of the address."
        },
        "district": {
          "type": "string",
          "description": "The district of the address."
        },
        "buildingName": {
          "type": "string",
          "description": "The building name of the address."
        },
        "buildingFloor": {
          "type": "string",
          "description": "The building floor of the address."
        },
        "buildingRoom": {
          "type": "string",
          "description": "The building room of the address."
        },
        "buildingZone": {
          "type": "string",
          "description": "The building zone of the address."
        },
        "crossing1": {
          "type": "string",
          "description": "The first crossing of the address."
        },
        "crossing2": {
          "type": "string",
          "description": "The second crossing of the address."
        }
      }
    },
    "longitude": {
      "type": "number",
      "description": "The longitude."
    },
    "latitude": {
      "type": "number",
      "description": "The latitude."
    },
    "scopes": {
      "additionalProperties": false,
      "type": "object",
      "description": "Project and user scopes arrays.",
      "required": ["users", "projects"],
      "properties": {
        "users": {
          "type": "array",
          "description": "An array of Application User IDs this resource is scoped to.",
          "items": { "type": "string" }
        },
        "projects": {
          "type": "array",
          "description": "An array of project IDs this resource is scoped to.",
          "items": {
            "type": "string",
            "description": "The ID of this resource.",
            "pattern": "^[abcdefghkmnpqrstwxyABCDEFGHKMNPQRSTUVWXY0123456789]{24}$",
            "readOnly": true
          }
        }
      }
    }
  },
  "x-filterable-fields": ["name", "identifiers", "tags"]
}

{
  "street": "Float Street",
  "postalCode": "N16FG",
  "city": "London",
  "country": "United Kingdom"
}

Create a Place

🚧

Partial updates and position

If you PUT a partial update to an existing /places resource, please note that the position object will be cleared if it is not included in your payload.

Places are created using a POST request to the /places resource containing a JSON document.

POST /places
Content-Type: application/json
Authorization: $OPERATOR_API_KEY

PlaceDocument

curl -i -H "Content-Type: application/json" \
  -H "Authorization: $OPERATOR_API_KEY" \
  -X POST "https://$EVT_API_DOMAIN/places" \
  -d '{
    "name": "AS Garments Ltd.",
    "description": "Facility for AS Garments Ltd.",
    "position": {
      "type": "Point",
      "coordinates": [
        5.625,
        21.94304553343818
      ]
    },
    "address": {
      "street": "Float Street",
      "postalCode": "N16FG",
      "city": "London",
      "country": "United Kingdom"
    },
    "identifiers": {
      "gs1:414": "1234567890128"
    }
  }'

const payload = {
  name: 'AS Garments Ltd.',
  description: 'Facility for AS Garments Ltd.',
  position: {
    type: 'Point',
    coordinates: [
      5.625,
      21.94304553343818
    ]
  },
  address: {
    street: 'Float Street',
    postalCode: 'N16FG',
    city: 'London',
    country: 'United Kingdom'
  },
  identifiers: {
    gs1:414: '1234567890128'
  }
};

operator.place().create(payload)
  .then(console.log);

HTTP/1.1 201 Created
Content-Type: application/json
Location: https://$EVT_API_DOMAIN/places/UmBy2FXc6QQVhPaRaYNVErAb

{
  "id": "U7ahFRA2h8DUCfwRaHqRFygb",
  "createdAt": 1560772664271,
  "updatedAt": 1560772664271,
  "name": "AS Garments Ltd.",
  "description": "Facility for AS Garments Ltd.",
  "position": {
    "type": "Point",
    "coordinates": [
      5.625,
      21.94304553343818
    ]
  },
  "address": {
    "street": "Float Street",
    "postalCode": "N16FG",
    "city": "London",
    "country": "United Kingdom"
  },
  "identifiers": {
    "gs1:414": "1234567890128"
  },
  "longitude": 5.625,
  "latitude": 21.94304553343818
}

Read a place

Perform a GET request on the /places resource including the place's ID to read it.

GET /places/:placeId
Authorization: $OPERATOR_API_KEY

curl -H "Authorization: $OPERATOR_API_KEY" \
  -X GET "https://$EVT_API_DOMAIN/places/U7ahFRA2h8DUCfwRaHqRFygb"

const placeId = 'U7ahFRA2h8DUCfwRaHqRFygb';

app.place(placeId).read()
  .then(console.log);

String placeId = "UFR3PBUe7a2xDnbXQGYVnrGh";

Place place = apiManager.placeService().placesReader(placeId).execute();
System.out.println(place.getName());

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "U7ahFRA2h8DUCfwRaHqRFygb",
  "createdAt": 1560772664271,
  "updatedAt": 1560772664271,
  "name": "AS Garments Ltd.",
  "description": "Facility for AS Garments Ltd.",
  "position": {
    "type": "Point",
    "coordinates": [
      5.625,
      21.94304553343818
    ]
  },
  "address": {
    "street": "Float Street",
    "postalCode": "N16FG",
    "city": "London",
    "country": "United Kingdom"
  },
  "identifiers": {
    "gs1:414": "1234567890128"
  },
  "longitude": 5.625,
  "latitude": 21.94304553343818
}

Read All Places

Read all places associated with an account. The result may be paginated if there are more than 30 items.

GET /places
Authorization: $OPERATOR_API_KEY

curl -H "Authorization: $OPERATOR_API_KEY" \
  -X GET "https://$EVT_API_DOMAIN/places"

app.place().read()
  .then(console.log);

List<Place> places = apiManager.placeService().placesReader().execute();

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "id": "U7ahFRA2h8DUCfwRaHqRFygb",
    "createdAt": 1560772664271,
    "updatedAt": 1560772664271,
    "name": "AS Garments Ltd.",
    "description": "Facility for AS Garments Ltd.",
    "position": {
      "type": "Point",
      "coordinates": [
        5.625,
        21.94304553343818
      ]
    },
    "address": {
      "street": "Float Street",
      "postalCode": "N16FG",
      "city": "London",
      "country": "United Kingdom"
    },
    "identifiers": {
      "gs1:414": "1234567890128"
    },
    "longitude": 5.625,
    "latitude": 21.94304553343818
  }
]

Update a Place

PUT /places/:placeId
Content-Type: application/json
Authorization: $OPERATOR_API_KEY

PlaceDocument (subset)

curl -i -H "Content-Type: application/json" \
  -H "Authorization: $OPERATOR_API_KEY" \
  -X PUT 'https://$EVT_API_DOMAIN/places/UFR3PBUe7a2xDnbXQGYVnrGh' \
  -d '{
    "name": "AS Garments Subsidiary Ltd."
  }'

const placeId = 'UFR3PBUe7a2xDnbXQGYVnrGh';

const payload = {
  name: 'AS Garments Subsidiary Ltd.',
};

operator.place(placeId).update(payload)
  .then(console.log);

String placeId = "UFR3PBUe7a2xDnbXQGYVnrGh";

// Read a place
Place place = apiManager.placeService().placeReader(placeId).execute();

// Update it
place.setName("My Updated Place");
place.setDescription("Updated description of the place.");
place = apiManager.placeService().placeUpdater(placeId, place).execute();

HTTP/1.1 200 Ok
Content-Type: application/json

{
  "id": "U7ahFRA2h8DUCfwRaHqRFygb",
  "createdAt": 1560772664271,
  "updatedAt": 1560772789169,
  "name": "AS Garments Subsidiary Ltd.",
  "description": "Facility for AS Garments Ltd.",
  "address": {
    "street": "Float Street",
    "postalCode": "N16FG",
    "city": "London",
    "country": "United Kingdom"
  },
  "identifiers": {
    "gs1:414": "1234567890128"
  }
}

Delete a Place

To delete a place, simply send a DELETE to the place URL including the placeId. This action cannot be undone.

DELETE /places/:placeId
Authorization: $OPERATOR_API_KEY

curl -H "Authorization: $OPERATOR_API_KEY" \
  -X DELETE 'https://$EVT_API_DOMAIN/places/UFR3PBUe7a2xDnbXQGYVnrGh'

const placeId = 'UFR3PBUe7a2xDnbXQGYVnrGh';

operator.place(placeId).delete();

String placeId = "UFR3PBUe7a2xDnbXQGYVnrGh";

apiManager.placeService().placeDeleter(placeId).execute();

HTTP/1.1 200 OK

Get All Places Near Origin

The following request returns a (paginated) list of all places within a radius of a longitude and latitude location origin, sorted by distance. The query parameters are:

  • lon - Double
    Longitude of the search origin.

  • lat - Double
    Latitude of the search origin.

  • maxDist - Integer
    The radius from the origin in kilometres.

GET /places?lat=:lat&lon=:lon&maxDist=:maxDist
Authorization: $OPERATOR_API_KEY

curl -H "Authorization: $OPERATOR_API_KEY" \
  -X GET 'https://$EVT_API_DOMAIN/places?lat=49.5&lon=127.4&maxDist=20'

const params = {
  lat: 48.856,
  lon: 2.352,
  maxDist: 20,
};

app.place().read({ params })
  .then(console.log);

List<Place> places = apiManager.placeService().placesReader()
        .queryParam("lat", "48.856")
        .queryParam("lon", "2.352")
        .queryParam("maxDist", "20")
        .execute();
for(Place place : places) {
    System.out.println(place.getName());
}

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "id": "U7ahFRA2h8DUCfwRaHqRFygb",
    "createdAt": 1560772664271,
    "updatedAt": 1560772789169,
    "name": "AS Garments Subsidiary Ltd.",
    "description": "Facility for AS Garments Ltd.",
    "address": {
      "street": "Float Street",
      "postalCode": "N16FG",
      "city": "London",
      "country": "United Kingdom"
    },
    "identifiers": {
      "gs1:414": "1234567890128"
    }
  }
]

Set a Thng's Location to a Place

It is possible to set a Thng's location to a place by adding a location history item with the place ID.

curl -H "Content-Type: application/json" \
  -H "Authorization: $OPERATOR_API_KEY" \
  -X PUT 'https://$EVT_API_DOMAIN/thngs/UmCxU5c7BgPatpRawmWG7g6m/location' \
  -d '[{
    "place": "UkR2KhB7cGeMVmyENHxEXf2f"
  }]'

const thngId = 'UG4NgF9nBM8rtraRam9RreHg';
const placeId = 'UkR2KhB7cGeMVmyENHxEXf2f';
const payload = [{ place: placeId }];

user.thng(thngId).location()
  .update(payload)
  .then(console.log);

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "scopes": {
      "users": [],
      "projects": []
    },
    "timestamp": 1501160092412,
    "place": "UkR2KhB7cGeMVmyENHxEXf2f"
  }
]

Set an Action's Location to a Place

Similar to setting a Thng's location to a place, it is also possible to set an action's location to a place by its ID within the location object, and setting locationSource to "place".

{
  "type": "scans", 
  "thng": "UmCxU5c7BgPatpRawmWG7g6m", 
  "locationSource": "place", 
  "location": { 
    "place": "UkR2KhB7cGeMVmyENHxEXf2f"
  }
}

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": "U3EG8cFyegPw9pwawEeAmpKd",
  "createdAt": 1501160066085,
  "timestamp": 1501160066085,
  "type": "scans",
  "location": {
    "place": "UkR2KhB7cGeMVmyENHxEXf2f",
    "latitude": 10.1,
    "longitude": 125.6,
    "position": {
      "type": "Point",
      "coordinates": [
        125.6,
        10.1
      ]
    }
  },
  "locationSource": "place",
  "context": {
    "city": "Dartford",
    "region": "England",
    "countryCode": "GB",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_3) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/70.0.3538.77 Safari/537.36",
    "timeZone": "Europe/London"
  },
  "thng": "UmCxU5c7BgPatpRawmWG7g6m"
}