Any additional information such as speed or direction traveling is helpful, but not mandatory.

**We also have to collect GPS information on the vehicles every 5-25 seconds, but 15 seconds is ideal. Please confirm collection frequency with your provider**

We recommend talking directly to the account manager at the telematics provider. This request is common and can likely be executed within 24-48 hours. For many GPS providers, both the API Documentation and API key can be found on the telematics provider's website.

If you're working with a Transit Authority, around half of APIs are publicly available. We recommend going to the Transit Agency's website and looking for any information that suggests if the GPS information is public. Some keywords to use include: "Documentation", "App Developer Resources", "Developer Resources". "GTFS", "General Transit Feed System"; "Open Data", "MTA Open Data", etc... within these pages, operators can typically find the API Key and Documentation, or a way to request access to the feed.

If you're unable to find any information online, we recommend reaching out to the general manager at the Transit Agency. Depending on the size of the agency, the person responsible for this feed may differ. Determine the individual within the agency that has the ability to authorize the request. Many times the CIO (Chief Information Officer) will be the one to authorize the request. Here's an email template to use to reach them:

Hi [insert contact name],

We have recently started working with StreetMetrics to measure the effectiveness of ads placed on your vehicles.

In order to integrate with them, they’ve requested an API key to access your GPS real-time data feed. More specifically, they need the following information:

1. Documentation for the API that details how the data should be pulled

2. The format of the data (if not provided in the API documentation)

3. Any necessary credentials to access the API (API Keys, tokens, etc.)

Could you point me in the right direction to help them obtain this information? If there are any concerns sharing this information with them please let me know and I can connect you directly with their team.

Thanks,

For a step-by-step guide to integrate your GPS system, please reference the following documents:

API is the acronym for Application Programming Interface, which is a software intermediary that allows two applications to talk to each other. Each time someone uses an app like Facebook, sends an instant message, or checks the weather on a phone, they're using an API.

What Is an Example of an API?

When a vehicle moves, the GPS device on board connects to the Internet and sends its data to a server. The server then retrieves that data, interprets it, and presents the information to StreetMetrics in a readable way. StreetMetrics then retrieves the data, interprets it, and performs all necessary actions to begin the measurement process. This process is completed via API.

An API Also Provides a Layer of Security

A vehicle’s data is never fully exposed to the server, and likewise the server is never fully exposed to the vehicle. Instead, each communicates with small packets of data, sharing only that which is necessary. For StreetMetrics, we request the location of the vehicle, and the API tell us where the vehicle is.

API documentation is a technical content deliverable, containing instructions about how to effectively use and integrate with an API. It’s a concise reference manual containing all the information necessary to work with the API, with details about the functions, classes, return types, arguments and more, supported by tutorials and examples.

The provider varies based on the type of assets and media products being sold. For example, a company selling ads on a fleet of mobile billboards will likely be using a 1st or 3rd Party GPS solution, while a company selling ads public on transit fleets may be using GTFS.

These are the different types of GPS providers we work with:

General Transit Feed Specification - aka GTFS (used by most Transit Authorities)

Third-party GPS provider (e.g. OneStep, CalAmp, Samsara, or BrickHouse Security.)

First-party GPS solution (e.g. owned mobile app or GPS device)

identifying a provider

Operators vary based on the type of assets and media products being sold.

Yes. We're unable to measure the vehicles unless we have access to the vehicles trip history data.

Requesting access to the real-time GPS feed from the vehicles themselves. To get

access to this information, request an:

Requesting access to the real-time GTFS feed from the vehicles themselves. To get

access to this information, request an:

An API token is an alphanumeric code, unique to the GPS provider's accounts, which can be used from any system to validate StreetMetrics API calls. If an API was a doorway, the API token would be the key that unlocks the doorway.

API Integration (Pull): *Required for GTFS Integration* (Most Popular)
For an API PULL Integration, StreetMetrics will retrieve, or “pull”, the GPS data from the GPS Provider or other API
feed. Please email us the following:
a. Documentation for the API that details how the data should be pulled
b. The format of the data (if not provided in the API documentation)
c. Any necessary credentials to access the API (API Keys, token, etc.)

API Integration (Push)
For an API PUSH Integrations, StreetMetrics will receive GPS data that the client “pushes” to the StreetMetrics API
ingestion endpoint. The endpoint accepts POST and PUT requests, and follows the endpoint schema of:
​https://hermes.streetmetrics.io/ingest/IDENTIFIER. Please email the following:
a. A JSON object that shows the format of the data we will receive
b. Payload Frequency (seconds) - how frequently the data will be delivered (e.g. 5, 10, 15, 30 seconds)

For a seamless third-party integration, we recommend using one of the following preferred providers:

OneStep, CalAmp, Samsara, or BrickHouse Security.

If your business utilizes a non-preferred GPS provider, please note that this may lead to integration delays and unforeseeable issues following integration.

We recommend that the GPS capture the location of each vehicle every 5-10 seconds; however, we can work with pulling GPS data up to every 25 seconds. This process allows StreetMetrics to confidently route the vehicles.

StreetMetrics doesn't need to receive the GPS information in real time. As long as the GPS is capturing the location of the vehicle within the time range specified above, the data can be sent to StreetMetrics in batches every 1 minute up to every hour.

Below is an example of an adPlay schema:

{

“timestamp”: “2020-10-20T04:00:13.176245Z”,

“device_id”: 1409656909085260368,

“creative_id”: “Glass Bottle”,

“start_location”: [40.750921, -73.987718],

“end_location”: [40.751921, -73.988718],

“duration”: 10375

}

No. The values can be “vehicleId” instead of “vehicle_id.”

It isn't mandatory, but it does make the process easier. If the campaign object isn't included in the schema, we ask that the creative be sent with some campaign name prepended. Adding an additional campaign object to the schema wards off any potential issues in the future where the formatting of the creative name might change.

If unable to send a campaign object, group creatives by campaign manually in the StreetMetrics platform.

Yes -- we actually prefer it sent in batches, between every 15 - 60 seconds.

No. Send the ad play data as it comes, or send in groups every 10-30 seconds. Our standard instance can receive up to 100 ad plays per second, and will scale as the number of requests increase.

Yes. For digital ads on vehicles, we collect the GPS data from each ad play that is sent to us.

Mandatory Objects:

start_timestamp

vehicle_id

creative_id

start_location

duration

Optional Objects:

end_timestamp

market

speed

vehicle_direction

If the data is un-sequenced, then “end_location” is mandatory. Additionally, we ask that the "creative_ id" remain consistent.

Yes -- sequenced data doesn't include the end location of each ad play, rather the start of the following ad play. If the data is un-sequenced, we'll need the end location/timestamp for each ad play.

As a best practice, we recommend including the end timestamp/location for each ad play to avoid any potential issues.

We prefer sequenced data; however, as long as operators adhere to the data formats, we can work with non-sequenced data as well.

Yes. The GPS and CMS feeds need to be in sync in order for us to effectively perform our analysis and give operators the ability to parse through the data. StreetMetrics needs to know where the vehicle was located when the ad play started and where the vehicle was located when the ad play ended.

StreetMetrics relies on a direct relationship between the road segment and the creative/vehicle ID to accurately measure and attribute exposure to each individual ad play. Confirm the CMS provider is able to accommodate when the objects in the schema are created/identified.

No, StreetMetrics does not sync the feeds together. The operator completes this process directly.

StreetMetrics doesn't automatically create a campaign based on relevant campaign information sent in the schema.

It should be possible for most DSPs to get StreetMetrics the ad play data, but it can vary depending on the DSP.

After the bid request is made, the DSP sends StreetMetrics the schema associated to each ad play via API.

We recommend making the unique identifiers some sort of plaintext ID, rather than numerical or UUID. Unique identifiers are used for presentational purposes in the StreetMetrics dashboard.

If creative IDs have identical names, we recommend pre-pending some unique campaign identifier to the creative ID itself so we can delineate between them in our system.

As long as it remains consistent, StreetMetrics will accept any "timestamp" payload.

​