The Basics

Connecting to the API

Genscape’s Data API service environment can be found at: https://api.genscape.com/

API Keys

API keys should be considered the same as a password. DO NOT share or distribute your key. If you feel your key has been compromised, a new key can be regenerated in the API Profile section under the My Accounts menu.

Every request to the Genscape Data API requires an API key to be passed along with the request. Your API keys can be found in the API Profile section under the My Accounts menu.

Every API-entitled Genscape user will automatically get one API key. The Genscape Data API expects your key to be passed via the URL with the genApiKey parameter. So if your API key was abcdef and you were requesting North America current megawatts transmission data, you would send a request to https://api.genscape.com/power/na/v1/generation-transmission/current/?genApiKey=abcdef.

Alternatively, you can pass the API key using the HTTP header:

curl -v -X GET "https://api.genscape.com/power/na/v1/generation-transmission/current?limit=200&offset=0&format=json"
-H "Gen-Api-Key: {API key}"

Return Types

The Genscape Data API service offers 3 return types: JSON, XML and CSV. Just like your API key, you can specify the return type by passing the format parameter in the query string of the request. The options you can pass are json, xml, or csv. If you do not pass any format parameter, JSON will be returned.

Sending Endpoint Arguments

When sending data to the Data API service for filtering on listing endpoints, you should pass all your data using application/x-www-form-urlencoded strings. For GET methods, these are passed via the query string (after the "?" in the request URL).

Request Limit

Genscape has a bandwidth rate limiting system in place to prevent abuse and system overload. If you receive a response code of 429, that means you have exceeded the rate limit and you should send your requests at a slower rate. Our rate limits currently are subject to the following restrictions:

  • 30 requests per minute
  • 1,000 requests per day

Note that these limits are current guidelines only and are subject to change without notice. The counter resets every night at midnight Eastern Standard Time.

Response Codes

  • All requests will return an appropriate response code.
  • An error response will describe the specifics of any errors.
Success Response Code Response Name Description
200 OK Request was fulfilled
Error Response Code Response Name Description
400 Bad Request Request had bad syntax or the parameters supplied were invalid
403 Forbidden Valid API Key was not supplied in the query
404 Not Found Server has not found a route matching the given URI
503 Service Unavailable Server is currently unavailable
500 Internal Error Server encountered and unexpected condition which prevented it from fulfilling the request
429 Too Many Requests The allowed number of requests has been exceeded