Contents |
URL
https://api.geoloqi.com/1/place/create
Description
Create a new place in a layer.
Supported Request Methods
POST
Scope
place
Parameters
You can create a place either by specifying a latitude, longitude and radius, or by using the built-in geocoder to create a place given an address.
Latitude/Longitude
- latitude RequiredThe latitude of the center of the place
- longitude RequiredThe longitude of the center of the place
- radius OptionalThe radius of the the place in meters. If not set, the place will be considered a "point" and no geofencing features will be enabled for the place, but nearby queries will still work.
- span_longitude OptionalThe longitudinal span of the place. Radius is calculated from this span internally.
Geocoding
- geocode RequiredThe one-line text to geocode. Fully-specified addresses are recommended, but city names and some business names will work as well. Include the city and state for best results.
- radius OptionalIf no radius is specified, a radius will be automatically chosen based on the size of the feature returned from the geocoder. Addresses will usually result in a radius of 150 meters, while city names will be much larger
Other Parameters
- layer_id OptionalThe ID of the layer to create this place on. If omitted, the default layer is used.
- key OptionalA unique identifier for the place. See the page on De-Duplication for more information
- name OptionalThe name of the place to create.
- description OptionalYou can provide a description of the place, which will be displayed on the place's public page (if the layer is public)
- extraA hash of keys and values to store along with the place. Whatever you store here will be returned whenever the place info is read, as well as in the Trigger Callback. See Extra Parameters for more details.
- date_fromIf provided, the place will only be valid starting on this date
- date_toIf provided, the place will only be valid until this date
- time_fromIf provided, the place will only be valid starting at this time (of every day)
- time_toIf provided, the place will only be valid until this time (of every day)
All dates must be provided in ISO8601 format. The date portion will be ignored for the time_from
and time_to
parameters
For example, you can create a place that exists only from 5pm until 10pm of every day by specifying the time_from
and time_to
parameters.
Example Post Body
{ "layer_id":"1Wn", "name":"Example Place", "latitude":45.5037078163837, "longitude":-122.622699737549, "span_longitude":0.62, "extra":{ "description":"Portland", "url":"http://en.wikipedia.org/wiki/Portland" } }
or
{ "name":"Home", "latitude":45.5037078163837, "longitude":-122.622699737549, "radius":240 }
Response
Success
If the place was created successfully, you will get the place ID in the response and a "200 OK" response code.
HTTP/1.1 200 OK {"place_id":"r8f413"}
Errors
Places must be named uniquely per layer. If a place already exists with the name provided, you will get a "409 Conflict" response code, but the response body will be identical to a successful request. Additionally, there will be a "Location" header with the URI of the existing place.
HTTP/1.1 409 Conflict Location: http://api.geoloqi.com/1/place/info/C8f233 {"place_id":"C8f233"}
If there was an error, you will get a different response code such as "400 Bad Request" and the JSON returned will contain a descriptive error message. See Error Codes for more information.
{ "error": "missing_input", "error_description": "Radius in meters is required" }