Frequently Asked Questions
Setup
- How do I get access to your APIs?
You can register on our developer portal (http://tms.mashery.com/member/register) and you will receive a key that will enable you to have limited access to a few of our API methods. If you would like additional access, please contact us and request access.
- I have a Mashery login. Can I use this to gain access to your portal?
Yes, you can sign in to our developer portal (http://developer.tmsapi.com) using an existing Mashery key. From there you can register an application and request access. As noted above, you will receive a key with limited access privileges; a contract is required to have full access to the OnConnect Managed Services product. You are able to review our documentation (http://developer.tmsapi.com/docs) in order to preview the service.
- I created an account on the portal, but I can’t access the APIs. What do I do now?
If you are able to login to the portal, check your My Account page to determine if you have a key. If not, please contact us at customercareelectronic@gracenote.com.
- Can I get a free trial? If so, for how long and what data?
Yes. When you register for an account, you will receive a key that gives you limited access to the APIs. You may request to be upgraded to a free Sample plan that enables you additional access for 30 days. Please contact Gracenote sales by completing this form.
- Do I have to pay to use your APIs?
Yes, currently a contract is required to fully utilize our services. For more information, please contact us by completing our form.
- I have a sample or R&D key that has rate limits. We are ready to move into production, how can I get the limits removed?
Once you have signed a contract, we will remove the limits placed on your key and you may use the key for production purposes.
- How are your API levels and pricing structured?
The public plan is available for free when you register on the portal. The sample plan, which provides more complete access to the APIs is available at no charge when approved by our sales team. R&D and Production access are only available via a contract. Please contact our sales department for pricing.
Back to Top
Administration
- I have an account but I forgot my password. How do I recover it or get a new one?
On the sign in page you will see a link to recover your password or your username. To recover your password, you will be required to enter the email address and username you used to create the account. To recover your username, you will be required to enter your email address.
- I have a key, but I am unable to get a call to work properly. What do I do next?
The first place to start would be the Gracenote API Explorer, our interactive documentation (http://developer.tmsapi.com/io-docs). Once you are logged in, your key will be automatically populated and you can create calls to the APIs. Once you have created a call, it will show you the Request URI and other information that should help to get you started. You can also refer to our long form documentation located at http://developer.tmsapi.com/docs for more information. Lastly, you can contact us at http://developer.tmsapi.com/contact and give us as much information as possible. We will review the issue and hopefully respond with a solution that will get your on your way to developing with our APIs.
- Do you have documentation for your APIs?
Yes, we have two forms of documentation; standard, long form or I/O (interactive). The standard documentation may be found here: http://developer.tmsapi.com/docs. It includes in-depth information about the various API methods including how to call them and the responses. There is also a Reference section that includes details about time formats, image sizing and error handling. The Gracenote API Explorer or interactive documentation may be found here: http://developer.tmsapi.com/io-docs. This method allows you to create calls in real time to our data. It displays the request URI, response headers and the data response. This is a great source to use to try out various calls and review the responses.
Back to Top
Data Related Questions
- What is this field?
Our documentation includes descriptions of the fields that will be included in specific responses. For example, see the Response Body section for the Lineup Airings method here: http://developer.tmsapi.com/docs/read/data_v1/lineups/Lineup_Airings_TV_Grid
- I think this data is incorrect. How do I report that?
Please email us at customercareelectronic@gracenote.com. Please provide as much detail as you are able about the issue and we will respond promptly.
- Why do you only return one image reference for a show? I know that Gracenote has more images?
For phase one of the OnConnect Managed Services APIs we made a decision to return a “preferred” image for a particular movie or show. Our Program Images method allows you to retrieve all of the images that are related to a particular show or movie. Our Media Cloud hosting service includes references to all of the images we provide in our products.
- I see image references in the API returns. How do I get access to those images? Do you offer a hosting solution for images?
Access to images is included in your data agreement with TMS. You have two options to retrieve and display the images: Media Cloud, our image hosting service or retrieval via FTP. If you are interested in utilizing Media Cloud, please contact us by filling out our form. We will provide you with a custom sub domain that you will use to provide an absolute URL to the image being returned in the API responses. This is by far the simplest and most efficient way to deliver images to your customers. You may also retrieve images via FTP, but you will be required to store and manage those images via your own systems. If the image paths are maintained, you may utilize the relative path we provide to the image to display them.
Back to Top
More Technical Questions
- I am making a call, but I am getting an error message. What does that mean?
Please refer to the Reference page of our documentation for more details on error messages (http://developer.tmsapi.com/docs/read/data_v1/Reference). If an API call results in an error, we will return an HTTP status code in the header field and in the message body if applicable. Error codes that are returned in the response body are usually indicative of a problem with the request. For example, if you receive an error code of 1001 it means you are missing a required parameter. For most error codes you will see both the code number and the message.
- I need to get the data in XML instead of JSON. Do you support XML?
Our goal is to support both formats. Currently the TMS Data Delivery APIs are JSON and the Online Video Data APIs are XML.
- I am making a call and I keep getting gateway timeout errors. What is wrong?
The 504 Gateway Timeout error is an HTTP status code that means that one server did not receive a timely response from another server that it was accessing while attempting to load the web page or fill another request by the browser or a program. This usually means that the other server is down or not working properly. If you are a customer, please submit a support request using email to customercareelectronic@gracenote.com and we will investigate the issue.
- I made a call and I am not receiving any data in the response. I get [] in the response body of the I/O docs. What’s wrong?
The [] symbols mean there is no data that matches your call. You may need to adjust the time parameter or other parameters in order to get back data. For some methods such as Program Airings, a particular program may not be airing on your selected schedule within the 14-day window.
- Is there a limit to the number of calls I can make per second or a limit to the number of calls I can make in one day?
For public, sampling and R&D accounts, there are limits to the number of calls you can make per second and per day. The key rate limits are viewable on the “My Account” page of the developer portal.
- How do I retrieve detailed Celebrity information?
Many of the API methods such as Program Details include cast and crew information. You can retrieve the personId from that response and pass it to the Celebrities Details method to retrieve detailed information about your chosen celebrity.
- Do you support gzip?
Yes, we support gzip. It can be advantageous to implement this for methods such as the Lineup Airings (TV Grid) where the response size may be large.
- I am using your I/O docs and the browser freezes up at times. What should I do?
This is a known issue and you will just need to kill the page or reload the page. We have found that the developer portal and the I/O docs in particular perform best with Google Chrome.
- Do you have different versions of your API? What happens if I am using an older version and you introduce a new one? Will I have to upgrade and if so, how long do I have?
Our goal is to follow the semantic versioning specification listed here: http://semver.org/. We currently don’t have a set policy on how long we will maintain older versions of our APIs, but you will be encouraged to upgrade to the latest version.
- I want to improve the performance of my app. Can I cache your data on my side and if so, for how long? What are the limitations?
We currently have a short TTL (time to live) cache setting implemented for the TMS Data Delivery APIs, but you may cache data on your side based on your particular needs. There may be some content such as schedule data and some programming data that is updated frequently and you will want to set your cache settings with this in mind. Please contact us for more specifics.
Back to Top
Bug/Blocking Questions
- Is your API down? Do you have an API “health” or status page?
Our status page is available here: http://status.tmsapi.com
- Can I get access to reports on how many requests I am making?
Yes, navigate to the My Account page (http://developer.tmsapi.com/apps/mykeys) and for each key you are assigned, you will see a View Report link. Select that link and you may view your usage data.
- How do I report problems?
If you experience a problem that is impeding your development efforts or application in some way, please email us at customercareelectronic@gracenote.com. A case that is not a problem, bug or defect may be a request for an enhancement or additional functionality to be added to the product.
Back to Top