Ginzametrics API for SEO
The Ginzametrics API lets agencies and advertisers use Ginzametrics as a critical piece of their marketing infrastructure and automate key SEO functionality.
The API is not currently available to all users but we will gradually provide access to those customers who request it, as we are able to support them. Users of our paid plans will be given priority.
If you would like to gain access to the API, please email support@ginzametrics.com.
Getting Started
Once you have been given access to the API, you can access your API key by going to your user settings page.
On your settings page, at the bottom of the screen, find your API key.
About the API
The API is designed to be simple, usable and accessible from any client. The default output format is JSON and the API commands generally follow REST design principles.
You can test all of the API calls from the command line using cURL:
curl https://app.ginzametrics.com/v1/list_sites -d api_key=API_KEY -d format=jsonQuota
The API has an initial quota of 10 requests per hour. As there are not many commands at the moment, this should be sufficient in production but if you need your quota increased during development, please email support@ginzametrics.com with your request. We will be increasing this quota at a later date.
API Methods
1. Get API Version
Returns the current API version and copyright notices
Required Parameters
None
Example
curl https://app.ginzametrics.com/v1Sample Output
Ginzametrics API v1.1 Beta Copyright 2011 Ginzamarkets, Inc. All Rights Reserved2. List Accounts
List all of the accounts that you have access to on the user account associated with the given API key.
Required Parameters
api_key: the API key found in your user settings
format: the output format. The only valid format at this time is json
Example
curl https://app.ginzametrics.com/v1/list_accounts -d api_key=API_KEY -d format=jsonSample Output
This method will return a JSON structure representing one or more accounts, with associated metadata such as global_key (for the account, not the site), url, analytics_system, etc. The most important element you will need from each site is the global_key.
[{
{
"account": {
"name": "Ginzamarkets, Inc.",
"global_key": "1295609923f3",
"currency": "usd"
}
},
{
"account": {
"name": "Hotels",
"global_key": "a6d6104803mf",
"currency": "usd"
}
},
{
"account": {
"name": "Education",
"global_key": "33a427294d46",
"currency": "usd"
}
},
{
"account": {
"name": "Travel",
"global_key": "acb3028392mf0",
"currency": "usd"
}
}
}]3. List Sites
List all of the sites that you have access to on the user account associated with the given API key.
Required Parameters
api_key: the API key found in your user settings
format: the output format. The only valid format at this time is json
Example
curl https://app.ginzametrics.com/v1/list_sites -d api_key=API_KEY -d format=jsonSample Output
This method will return a JSON structure representing one or more sites, with associated metadata such as domain, url, analytics_system, etc. The most important element you will need from each site is the global_key.
[{
{
"site": {
"created_at": "2010-06-29T20:44:40Z",
"title": "ginzametrics.com",
"url": "http://ginzametrics.com/",
"domain": "ginzametrics.com",
"global_key": "aaef64ae1344z",
"meta_description": "Ginzametrics is a powerful, easy-to-use SEO (Search Engine Optimizaiton) Dashboard. ",
"analytics_system": "Google Analytics"
}
},
{
"site": {
"created_at": "2010-12-25T09:11:53Z",
"title": "ginzametrics.jp",
"url": "http://ginzametrics.jp/",
"domain": "ginzametrics.jp",
"global_key": "19ef64881344p",
"meta_description": Ginzametricsは、パワーフルで使いすいSEO（検索エンジン最適化）ツールです。",
"analytics_system": "Google Analytics"
}
}
}]4. List Markets
List all of global markets that Ginzametrics currently supports. The output of this command is typically used to get a country code for use when creating a new site via API.
Required Parameters
api_key: the API key found in your user settings
format: the output format. The only valid format at this time is json
Example
curl https://app.ginzametrics.com/v1/list_markets -d api_key=API_KEY -d format=jsonSample Output
This method will return a JSON structure representing the available markets on Ginzametrics.
[{
"geo": {
"name": "jp"
}
},
{
"geo": {
"name": "us"
}
},
...
{
"geo": {
"name": "gr"
}
}]5. Number of Active Keywords
Return the number of active keywords for the site in question.
Required Parameters
global_key: the global_key is a system-wide unique identifier for an individual website registered with Ginzametrics. It is a required part of the URL for any methods that are site-specific.
api_key: the API key found in your user settings
format: the output format. The only valid format at this time is json
Example
curl https://app.ginzametrics.com/v1/sites/GLOBAL_KEY/active_keywords -d api_key=API_KEY -d format=jsonSample Output
This method will return an integer value equal to the number of active keywords on the site. The return value of this method is used as the count parameter in the Latest Rankings command.
3066. Latest Rankings
Ginzametrics generally collects search engine ranking data on a daily basis. This method will return the latest rankings, visits and conversions (if any) from organic search. If there are no rankings found for a given keyword, either the values 999 or 9999 will be returned.
Required Parameters
global_key: the global_key is a system-wide unique identifier for an individual website registered with Ginzametrics. It is a required part of the URL for any methods that are site-specific.
api_key: the API key found in your user settings
format: the output format. The only valid format at this time is json
count: the number of keywords to return in the results. At a later date this will be capped at 100 and additional parameters for paging through results will be provided.
Example
curl https://app.ginzametrics.com/v1/sites/GLOBAL_KEY/latest_rankings -d api_key=API_KEY -d format=json -d count=countSample Output
Returns a JSON representation of the latest rankings, broken out by keyword and search engine, along with any search referrals and conversions from organic search.
[{
"keyword": {
"name": "ginzametrics",
"google_us_previous_rank": "1",
"google_us": "1",
"yahoo_us": "1",
"visits": "26",
"conversion_percent": "3.8462",
"yahoo_us_previous_rank": "1",
"conversions": "1",
"active": "1"
}
},
{
"keyword": {
"name": "seo strategy that works",
"google_us_previous_rank": "1",
"google_us": "1",
"yahoo_us": "1",
"visits": null,
"conversion_percent": null,
"yahoo_us_previous_rank": "1",
"conversions": null,
"active": "1"
}
}
}]7. Latest Rankings Date
Generally, the date of the latest rankings will be the current date but you can verify the date of the latest rankings by calling this method.
Required Parameters
global_key: the global_key is a system-wide unique identifier for an individual website registered with Ginzametrics. It is a required part of the URL for any methods that are site-specific.
api_key: the API key found in your user settings
format: the output format. The only valid format at this time is json
Example
curl https://app.ginzametrics.com/v1/sites/GLOBAL_KEY/latest_rankings_date -d api_key=API_KEY -d format=jsonSample Output
This method will return a date string.
"2011-02-03"8. Add Site
Add a new website to an existing account. If the account has a plan that supports multiple sites and has open slots available, the site will be included in the existing plan. If not, it will be created under a new free plan.
Required Parameters
api_key: the API key found in your user settings
url: the url of the website
market: one of the markets that is returned from the List Markets command. Must be a valid two letter country code that is currently supported by Ginzametrics.
format: the output format. The only valid format at this time is json
Example
curl https://app.ginzametrics.com/v1/accounts/GLOBAL_KEY/add_site -d api_key=API_KEY -d format=json -d url=URL -d market=MKT Sample Output
If successful, the command will return a new site object. If not, an error message will return.
8. Add Keywords to Site
Add new keywords to an existing site. If the current plan for the site or account has no available keyword slots, then the keywords will still be added but set to inactive. When you upgrade to a larger plan, the keywords will automatically be activated.
Required Parameters
global_key: the global_key is a system-wide unique identifier for an individual website registered with Ginzametrics. It is a required part of the URL for any methods that are site-specific.
api_key: the API key found in your user settings
format: the output format. The only valid format at this time is json
keywords: a comma-separated list of keywords
Example
curl https://app.ginzametrics.com/v1/sites/GLOBAL_KEY/add_keywords -d api_key=API_KEY -d format=json -d keywords="kw1, kw2"Sample Output
A message indicated that keywords have been added will return.
Changelog
Changes to the API will be posted on the API changelog.
Bugs
If you find bugs with the API, please email us at support@ginzametrics.com.