Web Services

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&#223;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&#246;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>