close anchor

Locations

To get information on locations:

GET /locations

Parameters

Param Type Description Optional
id string The UUID of an individual location.
user string The UUID of the primary user identified with a location, being the user who initially entered it to the project, if known. Include an empty value to query for locations identified with no primary user.
order string Indicate, by providing a comma-delimited list, the field(s) by which to order entries found. Include a '-' prefix if descending order is preferred in a given field ('+' is inferred by default). If empty or not provided, these valid fields will not be explicitly included: city, country, date_time.edit, date_time.init, detail, division.code, division.text, id, postcode.
page integer Identify the page on which to begin delivering entries. If not provided, the default value of 1 will be inferred.
limit integer Indicate a total of up to 100 entries to be delivered. If not provided, the default value of 10 will be inferred.
data string Indicate, by providing a comma-delimited list, the data field(s) to be delivered by this endpoint. If empty or not provided, this endpoint will include by default each of the data field(s) identified with the location object.

The data object provided by this endpoint includes both a total (integer) of entries found, and an index (array) of location(s).

To post a location:

POST /locations

Parameters

Provide the input field(s) below as a JSON-encoded data object:

Param Type Description Optional
name string The name of this location, provided in the endpoint transaction locale.
country string The ISO 3166-1 alpha-2 code of the country to be identified with the location.
division object The principal division of the location, being either its designated ISO 3166-2 code (if defined, as provided by the /countries endpoint), or text.
city string The city provided for the location.
postcode string The postal or zip code entered for the location.
detail string The physical or postal details of this location not included in the other fields: this will tend to include variations of a unit and/or building number, cardinal direction or quadrant, block number, thoroughfare and/or post office box, etc. depending on the (preferably localized) format in which the user entered this information.
point string The geographic point to be identified with this location, provided as a comma-delimited textual value indicating both longitude and latitude, in that order.

The data object provided by this endpoint is the location inserted to the project.

Errors

If there is an endpoint transaction failure, or a problem with user input data, an error is provided:

ID/Type Description
invalid_country The country provided is not a valid ISO 3166-1 alpha-2 code.
invalid_country_division The principle division entered is not a valid ISO 3166-2 code or text.
invalid_geo_data_point The point is not a valid geographic location.

If an error is not described on this page, the platform-wide error table provides further information.

To edit or update a location:

PUT /locations

In order to edit a location entity, log in the user identified with the location (or a user with editor-level privileges).

Parameters

Provide the input field(s) below as a JSON-encoded data object:

Param Type Description Optional
id string The UUID of the location to be updated.
name string The name of this location, provided in the endpoint transaction locale.
country string The ISO 3166-1 alpha-2 code of the country to be identified with the location.
division object The principal division of the location, being either its designated ISO 3166-2 code (if defined, as provided by the /countries endpoint), or text.
city string The city provided for the location.
postcode string The postal or zip code entered for the location.
detail string The physical or postal details of this location not included in the other fields: this will tend to include variations of a unit and/or building number, cardinal direction or quadrant, block number, thoroughfare and/or post office box, etc. depending on the (preferably localized) format in which the user entered this information.
point string The geographic point to be identified with this location, provided as a comma-delimited textual value indicating both longitude and latitude, in that order.

The data object provided by this endpoint is the updated location.

Errors

If there is an endpoint transaction failure, or a problem with user input data, an error is provided:

ID/Type Description
invalid_country The country provided is not a valid ISO 3166-1 alpha-2 code.
invalid_country_division The principle division entered is not a valid ISO 3166-2 code or text.
invalid_geo_data_point The point is not a valid geographic location.

If an error is not described on this page, the platform-wide error table provides further information.

To delete a location:

DELETE /locations

In order to delete a location entity, log in the user identified with the location (or a user with editor-level privileges).

Parameters

Param Type Description
id string The UUID of the location to be deleted.

The data object provided by this endpoint is the deleted location.

Register for an Invitation
Thank you!
We'll be in touch.
First Name*
Last Name*
(optional) Business Name
Role*
Email*