Import-API

Updating the MdB via API is a simple way to automate this otherwise laborious task. Please work with people experienced in communicating with API's online. Each API session needs to be authenticated using documentation AXA: Atlas XML API, and all data sent with this API must be encoded as ISO 8859-1.
Please mind that all API requests are sent to one web server, meaning that if you have child sites, you need to use the URL for each child site. A communication operator with four sites will this need to run this API on four different URL's

Here is some example PHP code for using insert_posts():

$api_user = 12345; $api_key = "xxx"; $api_hash = ""; require_once 'Zend/Rest/Client.php'; $client = new Zend_Rest_Client("http://www.example.com/admin/edit/citynetadressess/plain/api.php"); $client->api_login($api_user, $api_key); $login = $client->get(); $api_hash = $login->hash_key->__toString(); $keys = array("citynet", "city", "...", "capacity", "tv"); if (($handle = fopen("addresses.csv", "r")) !== FALSE) {   $nr = 0;   while (($data = fgetcsv($handle, 1000, ";")) !== FALSE) {     $nr++;     if ($nr == 1){       continue; # Skip first row     } else {       $data = array_combine($keys, $data);       $inserts["line$nr"] = $data;       if ($nr % 100 == 0){         $status = insert_posts($inserts);         if (!strstr($status, "Could not")) unset($inserts);         print "$nr: $statusn";       }     }   }   if ($inserts){     $status = insert_posts($inserts);     print "$nr: $statusn";   } } function insert_posts($inserts){   global $client, $api_hash;   $client->insert_posts($api_hash, $inserts, "insert");   $inserted = $client->post();   if ($inserted->status == "failed"){     return "Could not insert posts: " . $inserted->message;   } else {     return $inserted->message;   } }

To visualize this request, below is a GET representation of the request:

http://www.example.com/admin/edit/citynetadressess/plain/api.php?method=insert_post&hash=XXXX &data[line1][citynet]=MNCMSN &data[line1][city]=Västerås &data[line1][area]= &data[line1][building]=2038+HSBs+Brf+Adam &data[line1][streetname]=Agnegatan &data[line1][streetnumber]=2 &data[line1][streetletter]=b &data[line1][resident]=Henrik+Söderlund &data[line1][zip]=72217 &data[line1][owner]=Sörensen,+Tove &data[line1][owneraddress]= &data[line1][ownerzip]= &data[line1][ownercity]= &data[line1][premise]=174 &data[line1][type]=3 &data[line1][date]= &data[line1][cpe]=3 &data[line1][cpetype]= &data[line1][socket]=AARY0101A01 &data[line1][nettype]=3 &data[line1][media]=0 &data[line1][keywords]= &data[line1][active]=0&mode=update&rest=1
Note that the string values aren't URL encoded properly in this example, for clarity. Also, we've added some spaces between arguments to make it wrap nicely for legibility. And also note that you should use POST, not GET for the requests.
clock

Timing

It is our explicit recommendation that you run your import script during the timeframe between midnight to 3 am in the morning. The reson for this is that we run an aggregation script for XSP export at 3 am, and if you have run your import, the daily data will include that for the service providers in the following day.
Another reason is that if you were to run this during daytime, and you empty the database and insert every row, then you'd have a empty or incomplete database during a time where end customer could be searching for their address. Also, during nighttime the resource pressure on the server is much lower.

Methods
API Endpoint: Import
Import-API för Marknadsdatabasen, för att automatisera uppdateringarna av adressdata
Endpoint URL http://www.example.com/admin/edit/citynetadressess/plain/api
Note that this API requires authenticated user id and IP address and a hashed api credential Note that this API requires authenticated user id and IP address and a hashed api credential

Use the API Credentials module in admin to set up API access for this module
  • Method: delete_post

  • Information


    This will delete the post that has the ID value sent. To find the ID of a given post, use the search() function.
  • Parameters
    1 hash string green abcd Your login hash from api_login()
    2 id integer green 2331805 ID of post you want to delete
    Example Query:
    http://www.example.com/admin/edit/citynetadressess/plain/api?method=delete_post&hash=abcd&id=2331805
  • success response


       <delete_post>
          <response>
             <message>Post 2331805 deleted</message>
          </response>
          <status>success</status>
       </delete_post>
  • Method: empty_database

  • Information


    Will empty the database connected to the site you execute the command on. "all" will delete all posts, while "old" will remove only the posts where the date field is earlier than today. Using it this way enables future connections to be added manually while the API only empties and updates connections that are already installed.
  • Parameters
    1 hash string green abcd Your login hash from api_login()
    2 mode string green old "all" for all posts, "old" for posts before today
    Example Query:
    http://www.example.com/admin/edit/citynetadressess/plain/api?method=empty_database&hash=abcd&mode=old
  • success response


       <empty_database>
          <response>
             <message>Deleted all posts from MDb where citynet is 'ABC'</message>
          </response>
          <status>success</status>
       </empty_database>
  • Method: insert_post

  • Information


    ARRAY should be an array with PHP notation, as such: data[citynet]=MNCMSN&data[city]=Hallstahammar...

    Using "update" performs a check in the database for a post that already fits the inserted post, and updates it. The unique key for comparing is comprised of the values in the fields "citynet", "building", "streetname", "streetnumber", "streetletter", "premise", "socket" and "type". If a post is found to match these values, it will be updated - even if the fields are empty (both in the request and the database). The array sent must follow the MdB specification

    All values is validated and aa error will be returned if it doesn't validate and the post isn't accepted.
  • Parameters
    1 hash string green abcd Your login hash from api_login()
    2 data array green ARRAY An array of fields to be inserted to the database
    3 mode string green insert "insert" for just inserting, "update" for first checking for old duplicate
    Example Query:
    http://www.example.com/admin/edit/citynetadressess/plain/api?method=insert_post&hash=abcd&data=ARRAY&mode=insert
  • failed response


       <insert_post>
          <response>
             <message>Post did not validate</message>
             <errors>
                <building>building can not be NULL</building>
                <zip>Value for zip does not validate</zip>
             </errors>
          </response>
          <status>failed</status>
       </insert_post>
  • success response


       <insert_post>
          <response>
             <message>Inserted 1 post successfully</message>
          </response>
          <status>success</status>
       </insert_post>
  • Method: insert_posts

  • Information


    ARRAY should be an array of arrays with PHP notation, as such: posts[post1][citynet]=MNCMSN&posts[post1][city]=Hallstahammar&posts[post1][citynet]=... where "post1" is the index of the post in the array.

    Using "update" performs a check in the database for a post that already fits the inserted post, and updates it. The unique key for comparing is comprised of the values in the fields "citynet", "building", "streetname", "streetnumber", "streetletter", "premise", "socket" and "type". If a post is found to match these values, it will be updated - even if the fields are empty (both in the request and the database). The array sent must follow the MdB specification

    The array accepted can only contain a maximum of 100 arrays (posts) for each request. If you have 1000 posts to insert, you need to run this function 10 times. The API will return how many posts that validated and was thus entered to the database.

    Using "post###" (no spaces!) as the key for each array (post) in the request helps you understand possible error messages easier, if you have an internal ID for the data, it might be wise to use that (i.e. posts[293749][citynet]=MNCMSN)

    Debugging
    Use the mode "update" and only a few posts for debugging purposes, and verify the actions via the search() method or the web interface.
  • Parameters
    1 hash string green abcd Your login hash from api_login()
    2 posts array green ARRAY An array of posts to be inserted to the database, each post in the array the same as a single to insert_post()
    3 mode string green insert "insert" for just inserting, "update" for first checking for old duplicate
    Example Query:
    http://www.example.com/admin/edit/citynetadressess/plain/api?method=insert_posts&hash=abcd&posts=ARRAY&mode=insert
  • failed response


       <insert_posts>
          <response>
             <message>2 errors</message>
             <log>
                <line2>
                   <building>building can not be NULL</building>
                </line2>
                <line3>
                   <building>building can not be NULL</building>
                </line3>
             </log>
          </response>
          <status>failed</status>
       </insert_posts>
  • success response


       <insert_posts>
          <response>
             <message>100 successes, 0 errors, 100 processed</message>
          </response>
          <status>success</status>
       </insert_posts>
  • Method: search

  • Parameters
    1 hash string green abcd Your login hash from api_login()
    2 search string green AARY0101A07 Search string
    3 mode string green socket Search mode
    Example Query:
    http://www.example.com/admin/edit/citynetadressess/plain/api?method=search&hash=abcd&search=AARY0101A07&mode=socket
  • success response


       <search>
          <response>
             <matches>
                <post_2331800>
                   <id>2331805</id>
                   <address>Agnegatan 2a</address>
                   <building>2038 HSBs Brf Adam</building>
                   <socket>AARY0101A07</socket>
                </post_2331800>
             </matches>
          </response>
          <status>success</status>
       </search>
#inlineditbutton