Data API GUI

Owned by Anna Lee (Unlicensed)
Last updated: May 19, 2017 by Morgan Soloway (Unlicensed)

The Data API allows you to run a variety of reports based on the UberAds geo-summary logs. To access, select "Data API" from the top navigation.

Job Queue

View existing Data API jobs and their status on the Job Queue screen.  Select "Job Queue" from the left panel to access. If there are no jobs listed in this table, click “Create Job” on the left panel to get started.


In the Job Queue list, you'll find the following information for each of your Data API requests:


  • Job ID: Job ID is a numerical designation to keep track of your requested Data API jobs.
  • Name: The name of the job if it was given one.
  • Status: There are four possible statuses for a submitted job:
    • Submitted: The job has been submitted but has not yet begun processing.
    • In Progress: The job is processing. You will be alerted via email when the job is complete.
    • Completed: The job is complete and the report(s) will be sent to you via email, or you can access via download in the UI. When the job is complete, the report will be visible under the various report type columns: Visitor, Device-based, or Path-to-Purchase (Read more about the different Report Types here). You may download the report by clicking on the name for each report type.
    • Failed: The job has failed. If you see this status, please contact your UberMedia account manager in order to assess the problem.
  • Request Date: The date the job was requested.
  • Company: The specific company the job is related to.

Create a New Job

Create a new job by clicking on “Create Job” in the left panel. This will send you to the Create New Job screen.



Enter the following information into the Create Job page. All fields are required unless otherwise noted:

  • Polygon Format: Polygons are bounding boxes drawn around a location on a map such as a retail store. Each Data API job requires a valid GeoJSON or KML string. The Data API can also accept ESRI Shapefiles. For details on how to load ESRI Shapefiles, see below. After selecting the correct format, paste the GeoJSON or KML string in the text box.
    • ESRI Shapefiles: Due to the detailed nature of ESRI Shapefiles, please be sure your Shapefiles are properly formatted.
      • Format: Usually, an ESRI Shapefile will contain three or more files (.shp, .dbf, and .shx plus others such as .prj). These associated files must be zipped together into one file for use here (the files must be in the root of the zip file). Do not place these files into a folder and then zip the folder. Please note that there should be no spaces in any of the file names.
      • ESRI Reference Field Name: This is the reference field in the ESRI Shapefile which refers to the polygon name information. Often this is just "name", but it is possible that there is another term for this field. This is set by the Shapefile creator, and cannot be predicted, so it must be included in the request. It can be found in the ESRI Shapefile metadata, as a string field.


                           

                              

    • Draw a Polygon: Select the "Draw" tab to draw a polygon for use in the API.
      • Use the search field to find the correct location, and select the "Draw a Shape". Click to place each point on the polygon; click the original point to close the polygon.

                         

  • Objective: What are you trying to learn? There are three report types, with multiple options for each. At least one report selection is required, and you may select one report from each report type section. See below for information on each Report Type.
    • Select a report to see questions this report can answer, as well as understand more about the data that will be provided.

              

  • Timeframe: Set the period for when the analysis should occur.
    • Start Date and Time: The start date and time refers to the period for when the analysis should start. This must be at least greater than 48 hours prior to the the current day/time. Note that this uses UTC time zone.
    • End Date and Time: The end date and time refers to the period for when the analysis should end. This must be at least 48 hours prior to the current day/time. This time is not inclusive- if a job is submitted with an end time of 23:59:59, that is the cutoff time (it does not include any milliseconds beyond 23:59:59). If the full final second of that day is needed, the end date and time should be 00:00:00 of the next day. Note that this uses UTC time zone.
    • Day Parts: Click on the Day Parts link to open up additional day parting selections. See below for an explanation about how to use Day Parts in your analysis.
    • Seconds Before: An integer value that specifies the number of seconds before your selected date and time. This is required for Path-to-Purchase reports.  
    • Seconds After: An integer value that specifies the number of seconds before your selected date and time. This is required for Path-to-Purchase reports.
  • Report Details: Other details and parameters that can or should be included for a job.
    • Name: The name of the report. Use terms that make this report easily searchable by your team.
    • Additional Emails: Add any additional email addresses to receive reports, comma separated.
    • Include Full Geographic Info: Turning this field on will provide additional information including Country, State, Postal Code, and Census Block Group.
    • Friendly Dates: Turning this field on will convert any provided unix timestamp into date, time, and day of week. Users may select between UTC (the date, time, and day of week provided will be in UTC) or Local (the date, time, and day of will provided will be in the local timezone of the associated lat/long point)
    • Split File: Large files can be difficult to open in Excel. Setting this to true will split files that are over 1,000,000 lines. This only applies to tsv/csv files.
    • Shapefile Output: Now you can receive an ESRI shapefile output with your report. This is available for all reports types with lat/long in the final report output.

When the form is complete, select “Run Report” to submit the job. You will be redirected to the Job Status page and emailed with results when the report(s) are ready.

Create Another

If you would like to run multiple jobs with the same parameters, but different locations, select the "Create Another" checkbox at the bottom of the page, then select "Run Report" to submit the job. The the current job will be submitted, and the Create New screen will reload with the same parameters selected. However, the geojson/KML fields will be empty and ready for an alternate location.

Day Parts

When entering the Start and End Dates for your report(s), you can optionally choose to select Day Parts for the analysis. This enables you to see an analysis based on certain days and times of the week for the device in the local time zone. For example a device seen in PT at 1pm would be analyzed against a device seen at in ET at 1pm.


Recreate Job

If you would like to recreate a previously run job, hover over the job in the Job Queue to reveal a tab on the left with the Recreate Job button. Selecting this button will open up the Create Job screen, with all previously used parameters already selected. All fields can be edited before the job is submitted.

Please note: All KML and ESRI shapefiles are converted to GeoJson for analysis in the Data API. When recreating a job, the locations will appear as a GeoJson, but will remain the same.

Report Types

UberMedia provides a variety of reports that analyze devices seen within selected polygons.

  • Visitor Reports: Reports the number of devices seen in a polygon for a given time.
    • Zero Point Report: Provides information on devices seen in a polygon during the requested time period and the time stamps for each device's visit.
    • Visitor Count Report: Provides a total count of visitors in a polygon for the requested time period.
    • Pin Report: Provides information on devices seen in a polygon during the requested time period, including both the time stamps and exact lat/long points for each device's visit.
  • Device-based Reports: 
    • CEL/CDL Location Report: Provides the likely location that devices, observed in a polygon, spend the majority of their time. This could be in a residence or, for overnight workers, a business.  These high confidence locations are called CEL (Common Evening Locations)/CDL (Common Daytime Locations) and are NOT available for all visitors. Thus, the amount of device IDs listed is likely to be smaller than in a visit count report. The existence of a common daytime location does not imply that a common nighttime location is available and vice-versa. The determination of CEL/CDL uses multiple observation points across months of time, IP screening and other proprietary methodology.
    • Generator Report: Provides the likely origin point for a visitor (evening or daytime location), using a different methodology than CEL/CDL. This is done by evaluating the past 7 days of observation points for a device and has a lower confidence than CEL/CDL, but generally has a larger overlap with visitor counts.
  • Path-to-purchase Reports:
    • Pathing X Report: Provides information on where a device was seen prior to being inside a polygon. Note that “Time before appearance” is in seconds. Actual visits will be present in this report, but have a “Time before appearance” value of 0.
    • Pre-Post Report: Provides all the points a device was seen in the time before an appearance in the polygon AND the time after the appearance in the polygon.