APIs can be incredibly inefficient for bulk processing. Due to the size of the payload in these cases, a simple file upload allows for faster, more efficient processing and larger limits than possible via standard APIs. 

Background & Requirements

Common File Specification

1. File uploaded must be 
   

1. Tab delimited 
   
2. UTF-8 encoded
   
3. NOT compressed
   

2. The columns in the file will depend on the operation being performed. See individual operation details below
   
3. One row per keyword to be added/deleted/ad-hoc rank checked
   

1. Keywords must be lower case 
   
2. Keywords with invalid characters (adwords disallowed characters) or disallowed google commands (like site:) will be rejected automatically - and sent via email to client specified notification address
   

1. List of invalid characters '\', '!', '@', '%', '*', '?', '^', '~', '<', '>', '{', '}', ':', ';', '"', '¡', '¢', '£', '¤', '¥', '¦', '§', '¨', '©', 'ª', '«', '¬', '®', '¯', '–', '—', '‘', '’', '‚', '“', '”', '„', '†', '‡', '•', '…', '‰', '€', '™', '°', '±','²', '³', '´', 'µ', '¶', '·', '¸', '¹', 'º', '»', '¼', '½', '¾', '¿', '�', 'cache:', 'site:', 'allinurl:', 'related:', 'info:'
   

4. File naming convention
   

1. yyyyMMdd##-[operation].txt
   
2. Date is the first part and must be in yyyyMMdd## format
   

1. ## indicates a numerical value from 00 to 99
   
2. This allows for up to 100 distinct uploads each day for each operation
   

1. NOTE: The processing time will depend on how many files and how many rows are uploaded for each file 
   

3. Duplicate file names (same date and same numerical identifier) are not allowed
   

3. Available operations
   

1. ADD
   
2. DELETE
   
3. ADHOC 
   

5. Limitations
   

1. Maximum 1,000,000 rows per operation
   

6. Processing Order
   

1. Files are processed in the order of upload
   

7. Timing
   

1. Timing is dependent on the number of rows and the number of tags processed
   
2. Typically, 100,000 rows with 1 tag each can be processed within a couple of hours 
   

1. Ad-hoc Rank checking is limited to 50,000 keywords per hour 
   

3. Keywords submitted by 4 pm Central time are typically sent to rank check the same day
   

1. 100,000 keywords can reasonably be rank checked before end of day if submitted by 4 pm Central time – but is not guaranteed
   
2. In case data was submitted after 4 pm or more than 100,000 keywords were submitted, full data would be available for the next full day
   

4. Data will be reflected in the UI the next day for Add and Delete operations
   

Bulk Programmatic Operations

Add

1. Adding keywords to a platform profile to start tracking moving forward
   
2. Adding the keywords to any tags specified
   

Add Specifications

1. In addition to common file specifications above
   
2. Filename
   

1. yyyyMMdd##-add.txt
   

3. Columns
   

1. Keyword
   

1. One keyword per row
   

2. Tags 
   

1. Multiple tags can be specified within the same row for each keyword but must be separated by !_! (exclamation underscore exclamation) within the field
   

4. Each row must contain a keyword 
   

1. A row with only the Tag column populated will be rejected – Keyword column cannot be blank
   

5. The order of the columns is VERY important. “Keyword” in column 1 and “Tags” in column 2.
   

1. Any mistakes in column order will result in data being uploaded wrong
   

6. All keywords uploaded will be added to ALL national level engines enabled for the domain
   

1. Example: If you have Google Desktop and Google Mobile enabled for USA, all uploaded keywords will be added to both engines. This is a platform level requirement 
   

7. Logic
   

1. If no tag is specified then keywords will be simply added to the profile without tags
   
2. If one or more tags are specified for each keyword, keywords will be added to tags (keyword + tag relationship will be created)
   
3. If tag is specified and does not exist, a new tag will be created and keywords added to it
   
4. If keyword already exists, and no tag specified, it will be skipped
   
5. If keyword already exists and tag specified does not exist, the new tag will be created and keyword + tag relationship created
   

8. Ranking data
   

Add File Location

2. Once processed, the uploaded file will be moved to the /keyword_auto_upload/backup/yyyymmdd/ sub-folder by our system. 

5. Rejected keywords will be sent via email 

Delete

The delete operation provides 2 distinct capabilities:

1. Delete keywords from the profile and stop tracking them moving forward
   
2. Delete only the keyword + tag relationship but keep tracking keyword 
   

Delete Specifications

Nearly identical to the specifications for ADD  operation above, except for the logic of how delete of keywords and keyword+tags are handled

1. In addition to common file specifications above
   
2. Filename
   

1. yyyyMMdd##-delete.txt
   
2. ## indicates a numerical value from 00 to 99
   

3. Columns
   

1. Keyword
   

1. One keyword per row
   

2. Tags 
   

1. Multiple tags can be specified within the same row for each keyword but must be separated by !_! (exclamation underscore exclamation) within the field
   

4. Each row must contain a keyword 
   

1. A row with only the Tag column populated will be rejected
   

5. The order of the columns is VERY important. “Keyword” in column 1 and “Tags” in column 2.
   

1. Any mistakes in column order will result in data being uploaded wrong
   

6. Logic
   

1. If keyword does not exist, then we will skip
   
2. if keyword exists but tag does not exist, then we will delete the keyword only
   
3. If keyword and tag are both specified, ONLY the keyword+tag relationship will be removed
   
4. After keyword is deleted, if the tag is empty, it will stay in the platform
   
5. Cannot specify tags to be deleted only
   

Delete File Location

1. Files should be uploaded to the /keyword_auto_upload folder on the sFTP provided.

2. Once processed, the uploaded file will be moved to the /keyword_auto_upload/backup/yyyymmdd/ sub-folder by our system.

3. Do not upload any files into that sub-folder. It is meant to maintain an archive of operations performed

4. If our processing system encounters an error with the file uploaded, all rows that triggered an error will be exported into a file and placed within the /keyword_auto_upload/errors sub-folder

     4a. Error file name will be error-yyymmdd##.txt

5. Rejected keywords will be sent via email 

Ad hoc

The Ad hoc operation allows for uploading keywords for a 1-time rank check. These keywords do not get added to any of your profiles. Instead, they are processed separately, and the scraped results are exported out in your standard export format to the sFTP.

NOTE: Ad hoc rank checking has a separate cost as outlined in your work order. In case its not specified, please reach out to your Client Success Manager or support@seoclarity.net for information.

Ad hoc Specifications

1. In addition to common file specifications above
   
2. Filename
   

1. [yyyyMMdd##]adhoc-[engine]-[language]-[device].txt
   

1. ## indicates a value from 00 to 99
   

2. Where:
   

1. Engine is the country specific engine to rank check on
   

1. Google.com for USA
   
2. Google.co.uk for UK
   
3. Google.de for Germany 
   
4. And so on. In case of questions on the correct Google endpoint for a particular country, please contact support@seoclarity.net
   

2. Language is the 2 digit language code in ISO 639-1 format (https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes)
   

1. English is en
   
2. Spanish is es
   
3. French is fr
   
4. German is de
   
5. And so on. For help with the correct language code, please contact support@seoclarity.net  
   
6. In case where an incorrect or unsupoorted engine+language+country combination is specified, an error message will result. 
   

3. Device is one of the following
   

1. Desktop
   
2. mobile
   

3. Column
   

1. Keyword
   

4. Each row must contain a keyword 
   
5. Logic
   

1. All keywords that pass the guidelines are sent to be rank checked immediately
   

Ad Hoc File Location

Notifications

An email report is generated after each operation is completed and emailed to tss@seoclarity.net (adhoc ranking will also send to billing@actonia.com). Details of the processing can also be published to an Amazon SNS Topic. Please contact your Client Success Manager or support@seoclarity.net in order to setup the Amazon SNS Topic notification