Webservices

Die unten aufgeführten Webservice-Aufrufe ermitteln Standorte. Das Suchergebnis kann mit den folgenden Parametern eingeschränkt werden:

filter[per_page], filter[page]: Es wird nur ein Ausschnitt aus der Suchergebnisliste zurückgegeben. Der Wert von per_page beziffert die maximale Anzahl zurückzugebender Standorte und page den zurückzugebenden Ausschnitt.
filter[lat], filter[lng], filter[distance]: Mit dieser Kombination von Filtern können alle Standorte ermittelt werden, die sich im Umkreis (distance, in Kilometern) der durch lat (Breitengrad) und lng (Längengrad) spezifizierten geografischen Position befinden. Voraussetzung hierfür ist, dass die Standorte selbst über eine Positionsangabe verfügen.
filter[collection_id]: Mit diesem Filter wird die Suche nach Standorten auf diejenigen Accounts beschränkt, die in der als Wert angegebenen Account-Sammelliste enthalten sind.
include[]: Geben Sie als Wert dieses Parameters account an, wenn je ermitteltem Standort auch die Daten des Accounts zurückgegeben werden sollen, zu dem der Standort gehört. Die ID des Accounts ist immer in den Standortdaten enthalten, so dass die Account-Daten auch nachträglich ermittelt werden können.

Die Liste der Standorte ermitteln, paginiert

curl http://hostname/webservice/locations \
  -u webservice:apikey \
  -G \
  -d filter[per_page]='1' \
  -d filter[page]='2'

Als Ergebnis wird ein XML-Dokument geliefert, das im Element locations alle Standorte enthält, auf die die Filterkriterien zutreffen. Jeder Standort ist in einem location-Element enthalten.

<?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>

Standorte in einem Umkreis finden

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

Weitere Informationen über die Filter finden Sie in den Beschreibungen weiter oben.

Da include[]=account angegeben wurde, enthält das Ergebnis je Standort auch den Account, zu dem dieser gehört:

<?xml version="1.0" encoding="UTF-8"?>
<locations type="array">
  <location>
    <account_id type="integer">1</account_id>
    <account>
      <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>

Standorte in den Accounts einer Sammelliste suchen

curl http://hostname/webservice/locations \
  -u webservice:apikey \
  -G \
  -d filter[collection_id]=2

Das Ergebnis ist wie oben eine Liste von location-Elementen innerhalb eines locations-Elements.

<?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>

Daten eines Standorts über seine ID abrufen

Ist die ID eines Standorts bekannt, so können die Standortdaten mit dem folgenden Webservice-Aufruf ausgelesen werden:

curl http://hostname/webservice/locations/id \
  -u webservice:apikey

Als Ergebnis werden die Standortdaten in einem location-Element zurückgegeben:

<?xml version="1.0" encoding="UTF-8"?>
<location>
  <account_id type="integer">3</account_id>
  <address0>Example AG</address0>
  <address1>Musterstr. 15</address1>
  <address2 nil="true"></address2>
  <city>Berlin</city>
  <country>Deutschland</country>
  <id type="integer">3</id>
  <lat type="decimal">52.4327862</lat>
  <lng type="decimal">13.3742091</lng>
  <postal_code>12277</postal_code>
  <state nil="true"></state>
  <want_assign_geoloc type="boolean">false</want_assign_geoloc>
</location>

Standorte eines Accounts ermitteln

Mit dem folgenden Webservice-Aufruf lassen sich alle Standorte eines Accounts ermitteln:

curl http://hostname/webservice/locations \
  -u webservice:apikey \
  -G \
  -d filter[account_id]=3

Das OMC liefert, sofern der angegebene Account existiert, ein XML-Dokument mit allen Standorten (location) des Accounts im locations-Element. Beispiel:

<locations type="array">
  <location>
    <account_id type="integer">3</account_id>
    <address0>Example AG</address0>
    <address1>Musterstr. 15</address1>
    <address2 nil="true"></address2>
    <city>Berlin</city>
    <country>Deutschland</country>
    <id type="integer">3</id>
    <lat type="decimal">52.4327862</lat>
    <lng type="decimal">13.3742091</lng>
    <postal_code>12277</postal_code>
    <state nil="true"></state>
    <want_assign_geoloc type="boolean">false</want_assign_geoloc>
  </location>
</locations>

Einen Standort erstellen

curl http://hostname/webservice/locations \
  -u webservice:apikey \
  -G \
  -X POST
  -d location[account_id]=account_id \
  -d location[city]=Berlin \
  -d location[want_assign_geoloc]=false

Das OMC liefert als Antwort die Standortdaten:

<?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>

Einen Standort ändern

curl http://hostname/webservice/locations/id \
  -u webservice:apikey \
  -G \
  -X PUT
  -d location[city]=Hamburg \
  -d location[want_assign_geoloc]=false

Als Ergebnis dieser Anfrage wird der geänderte Standort geliefert.

Einen Standort löschen

Ein Standort kann nur gelöscht werden, wenn er keiner Kontaktperson zugewiesen ist.

curl http://hostname/webservice/locations/id \
  -u webservice:apikey \
  -G \
  -X DELETE

Als Antwort liefert das OMC eine entsprechende Meldung:

<?xml version="1.0" encoding="UTF-8"?>
<hash>
  <message>location deleted</message>
</hash>