To upload locations in bulk, use the MetaLocator.upsertLocations API method. This method can update and insert records in bulk simultaneously. It will also return the internal MetaLocator IDs assigned to the records provided, and optionally, an external key.
MetaLocator.upsertLocations
Use our API Test tool to obtain the latest documentation on this and other API methods.
Username (String) : Your MetaLocator Username
Password (String) : Your MetaLocator Password
Prevent Duplicates (String) : Enabling this option will cause MetaLocator to UPDATE records it finds with a matching Address, City, State, Postal Code and Country. If an external key is provided, the system will also UPDATE if it finds a match for the external key. Records not matched by either the address or external key will be inserted as new.
Skip Duplicates (String) : This option modifies the behavior of the Prevent Duplicates feature and only functions if the Prevent Duplicates is set to 1. In the case of a duplicate identified according to the rules above, the system will SKIP the row instead of updating it with the row provided.
Struct (String): A structure representing the CSV rows as described below.
The Struct for import follows the same rules as the CSV import system.
Each API call can only have a total of 201 members within this parameter. To upload more than 200 locations, call this method in succession with another set of 200 locations. The "header" value must be provided with each call. Also note that the member/name content must contain a unique row name, e.g row1, row2 as shown in the below example. If a unique value is not provided for the row name, the row will be ignored. Notice that fields containing values with commas inline are contained in double quotes.
<param>
<value>
<string>YOURUSERNAME</string>
</value>
</param>
<param>
<value>
<string>YOURPASSWORD</string>
</value>
</param>
<param><value><string>1</string></value></param>
<param><value><string>0</string></value></param>
<param>
<value>
<struct>
<member>
<name>header</name>
<value>
<string>Name,Description,Published,Address,Address2,City,State,PostalCode,Phone,Date,Country,Link,Email,language,lat,lng,StoreNo</string>
</value>
</member>
<member>
<name>row1</name>
<value>
<string>"Sample Location, LLC",,1,2301 MetaLocator Way,,Denver,Colorado,80205,303-325-5912,,United States,,,en-US,,,25</string>
</value>
</member>
<member>
<name>row2</name>
<value>
<string>Sample Location 2,,1,"2302 Meta, Locator Way",,Denver,Colorado,80205,303-325-5912,,United States,,,en-US,,,26</string>
</value>
</member>
</struct>
</value>
</param></pre>
A response for the above request might look like this:
<pre><methodResponse>
<params>
<param>
<value>
<struct>
<member><name>ids</name>
<value>
<array>
<data>
<value>
<array>
<data>
<value><string>326</string></value>
<value><string>25</string></value>
<value><string>updated</string></value>
</data>
</array>
</value>
<value>
<array>
<data>
<value><string>327</string></value>
<value><string>26</string></value>
<value><string>inserted</string></value>
</data>
</array>
</value>
</data>
</array>
</value>
</member>
</struct>
</value>
</param>
</params>
</methodResponse>
In the example above, the user was adding two new rows. The first row already existed in the database and was found under StoreNo. 25. The second record was new, and was therefore INSERTED.
Each row indicates the MetaLocator ID provided first shown as 326 below, followed by the External Key (if provided, shown as 25 below) then the operation performed, shown as updated below.
<data>
<value><string>326</string></value>
<value><string>25</string></value>
<value><string>updated</string></value>
</data>
The external key is optional, and is only returned if the user account contains an External Key field and it was provided during the API call.
To create an external key field, navigate to Data -> Fields -> New. Create a new field where the Field Type is External Key, as shown below:
The field *must* contain only unique values. Attempts to create new locations with duplicate external key values will result in an error message.