The web service calls below retrieve locations. The search result can be restricted by means of the following parameters:
filter[per_page]
,
filter[page]
: Only a section of the
search result list is returned. The value of per_page
specifies the maximum number of locations, page
the
number of the section to be returned.
filter[lat]
,
filter[lng]
,
filter[distance]
: By means of this
combination of filters you can determine all the locations within a
given distance
(given in kilometers) from a geographical
position specified by lat
(latitude) and
lng
(longitude). For this to work the locations
themselves must include their geographical position.
filter[collection_id]
: By
means of this filter, the location search can be restricted to those
accounts contained in the collection specified as the value of this
parameter.
include[]
: Specify
account
as the value of this parameter if the account to
which a location belongs should be returned for each location. The
account ID is always included in the location data, so that the
account data can also be queried subsequently.
Retrieving the List of Locations, Paginated
curl http://hostname/webservice/locations \ -u webservice:apikey \ -G \ -d filter[per_page]='1' \ -d filter[page]='2'
This call returns an XML document containing a locations
element with all the locations to which the filter criteria apply. Each location is contained in a location
element.
<?xml version="1.0" encoding="UTF-8"?> <locations type="array"> <location> <account_id type="integer">1</account_id> <address0>Babelsberger Straße 1</address0> <address1 nil="true"></address1> <address2 nil="true"></address2> <city>Potsdam</city> <country nil="true"></country> <id type="integer">2</id> <lat type="decimal">52.3719095</lat> <lng type="decimal">13.0493586</lng> <postal_code>14473</postal_code> <state nil="true"></state> <want_assign_geoloc type="boolean">false</want_assign_geoloc> </location> </locations>
Finding Locations within a Radius
curl http://hostname/webservice/locations \ -u webservice:apikey \ -G \ -d filter[lat]='52.516389' \ -d filter[lng]='13.377778' \ -d filter[distance]='10' \ -d include[]=account
For details about the filters, please refer to the descriptions above.
Since include[]=account
was specified, the result includes for each location the account to which it belongs:
<?xml version="1.0" encoding="UTF-8"?> <locations type="array"> <location> <account_id type="integer">1</account_id> <account> <custom1 nil="true"></custom1> <name>Deutsche Bahnhöfe</name> ... </account> <address0>Europaplatz 1</address0> <address1 nil="true"></address1> <address2 nil="true"></address2> <city>Berlin</city> <country nil="true"></country> <distance type="decimal">2.4591200321</distance> <id type="integer">1</id> <lat type="decimal">52.5231724</lat> <lng type="decimal">13.365317</lng> <postal_code>10557</postal_code> <state nil="true"></state> <want_assign_geoloc type="boolean">false</want_assign_geoloc> </location> </locations>
Finding Locations in the Accounts of a Collection
curl http://hostname/webservice/locations \ -u webservice:apikey \ -G \ -d filter[collection_id]=2
Like above, the result is a list of location
elements inside a location
element.
<?xml version="1.0" encoding="UTF-8"?> <locations type="array"> <location> <account_id type="integer">1</account_id> <address0>Europaplatz 1</address0> <address1 nil="true"></address1> <address2 nil="true"></address2> <city>Berlin</city> <country nil="true"></country> <id type="integer">1</id> <lat type="decimal">52.5231724</lat> <lng type="decimal">13.365317</lng> <postal_code>10557</postal_code> <state nil="true"></state> <want_assign_geoloc type="boolean">false</want_assign_geoloc> </location> <location> <account_id type="integer">1</account_id> ... </location> </locations>
Retrieving Location Data by ID
If the ID of a location is known, you can retrieve the location data using the following webservice call:
curl http://hostname/webservice/locations/id \ -u webservice:apikey
The location data is returned in a location
element:
<?xml version="1.0" encoding="UTF-8"?> <location> <account_id type="integer">3</account_id> <address0>Example Ltd.</address0> <address1>15 Lemon Street</address1> <address2 nil="true"></address2> <city>Downtown</city> <country>Great Britain</country> <id type="integer">3</id> <lat type="decimal">52.4327862</lat> <lng type="decimal">13.3742091</lng> <postal_code>6QW3X</postal_code> <state nil="true"></state> <want_assign_geoloc type="boolean">false</want_assign_geoloc> </location>
Retrieving an Account’s Locations
Using the following web service call, all locations of an account can be retrieved:
curl http://hostname/webservice/accounts/id/locations \ -u webservice:apikey \ -G \ -d filter[account_id]=3
If the specified account exists, the OMC returns an XML document containing all the locations of the account as location
elements enclosed in a locations
element. Example:
<locations type="array"> <location> <account_id type="integer">3</account_id> <address0>Example Ltd.</address0> <address1>15 Lemon Street</address1> <address2 nil="true"></address2> <city>London</city> <country>Deutschland</country> <id type="integer">3</id> <lat type="decimal">52.4327862</lat> <lng type="decimal">13.3742091</lng> <postal_code>6QW3X</postal_code> <state nil="true"></state> <want_assign_geoloc type="boolean">false</want_assign_geoloc> </location> </locations>
Finding Locations in the Accounts of a Collection
curl http://hostname/webservice/locations \ -u webservice:apikey \ -G \ -d filter[collection_id]=2
Like above, the result is a list of location
elements contained in a locations
element.
<?xml version="1.0" encoding="UTF-8"?> <locations type="array"> <location> <account_id type="integer">1</account_id> <address0>Europaplatz 1</address0> <address1 nil="true"></address1> <address2 nil="true"></address2> <city>Berlin</city> <country nil="true"></country> <id type="integer">1</id> <lat type="decimal">52.5231724</lat> <lng type="decimal">13.365317</lng> <postal_code>10557</postal_code> <state nil="true"></state> <want_assign_geoloc type="boolean">false</want_assign_geoloc> </location> <location> <account_id type="integer">1</account_id> ... </location> </locations>
Retrieving a Location by its ID
If the ID of a location is known, the location data can be retrieved using the following websevice call:
curl http://hostname/webservice/locations/id \ -u webservice:apikey
As the result, the location data is returned in a location
element:
<?xml version="1.0" encoding="UTF-8"?> <location> <account_id type="integer">3</account_id> <address0>Example Ltd.</address0> <address1>15 Lemon Street</address1> <address2 nil="true"></address2> <city>London</city> <country>Great Britain</country> <id type="integer">3</id> <lat type="decimal">52.4327862</lat> <lng type="decimal">13.3742091</lng> <postal_code>6QW3X</postal_code> <state nil="true"></state> <want_assign_geoloc type="boolean">false</want_assign_geoloc> </location>
Creating a Location
curl http://hostname/webservice/locations \ -u webservice:apikey \ -G \ -X POST -d location[account_id]=account_id \ -d location[city]=London \ -d location[want_assign_geoloc]=false
As the result, the OMC returns the location data:
<?xml version="1.0" encoding="UTF-8"?> <location> <city>Berlin</city> <address1 nil="true"></address1> <address2 nil="true"></address2> <country nil="true"></country> <postal_code nil="true"></postal_code> <account_id type="integer">2</account_id> <lng nil="true"></lng> <id type="integer">8</id> <want_assign_geoloc type="boolean">false</want_assign_geoloc> <lat nil="true"></lat> <state nil="true"></state> <address0 nil="true"></address0> </location>
Modifying a Location
curl http://hostname/webservice/locations/id \ -u webservice:apikey \ -G \ -X PUT -d location[city]=Hamburg \ -d location[want_assign_geoloc]=false
Again, the OMC returns the location data.
Deleting a Location
A location can only be deleted, if it is not referenced by a contact person.
curl http://hostname/webservice/locations/id \ -u webservice:apikey \ -G \ -X DELETE
As the result, the OMC returns a corresponding message.
<?xml version="1.0" encoding="UTF-8"?> <hash> <message>location deleted</message> </hash>