NAV
http

Introduction

Welcome to the GeoScreenshot API!

Getting Started

To get started:

  1. Sign up for a plan that supports API access here: https://www.geoscreenshot.com/pricing

  2. Generate an API key from My Account -> API

You will use the API key to authenticate your requests using the apikey GET variable.

Endpoints

Account Info

Get the current API key's email address and balance.

curl "https://api.geoscreenshot.com/me/?apikey=YOUR_API_KEY"

A successful request will return a response like this:

{
   "balance":2072,
   "email":"geouser@domain.com"
}

If you have an invalid API key, you will get an HTTP 401 error as follows:

{
   "name":"NotAuthenticated",
   "message":"Invalid API key passed",
   "code":401,
   "className":"not-authenticated",
   "errors":{

   }
}

Screenshot

A complete screenshot will process all of the following - A PNG Screenshot - Generated HTML - JavaScript Console Output in a JSON - HTTP Requests Archive - Cookies

Filtered Result Endpoints

If you would like a smaller JSON response, you can make a call to our filtered endpoints. This will still capture a complete screenshot, but it will return only a desired subset of the keys.

Filter Endpoint
png https://api.geoscreenshot.com/screenshot/png
html https://api.geoscreenshot.com/screenshot/html
har https://api.geoscreenshot.com/screenshot/har

Capture Google News from UK

curl "https://api.geoscreenshot.com/screenshot?apikey=YOUR_API_KEY&url=https://news.google.com&country=gb"

A successful response will return the following JSON format

{
"_meta": {
    "uid": "fabd8fa3-c4aa-4a0f-9894-a3580b31ec74",
    "startTime": 1591611008242,
    "endTime": 1591611020878,
    "duration": 12636,
    "instanceId": "516e8d0cbddbf6b25f4d0218f87336ec_0"
},
"_hash": {
    "perceptual": "b00c07ef7cf7b001f0c7f0417071f07330f17bf1f00731c1fff03000f040f3f3",
    "html": "15e0cdc83fe612e296339b958f9d6934c8d056908a5b47f31f92bce740e60843",
    "png": "9a93408fe05bc13d71db4220039a5f3454de19a1078f5bbc2825fc5391ead329",
    "console": "83f976263ba5eece3baa5ec655439f41257dd62f1d55dfd66b98d08eac97345b",
    "har": "14d08a710f8d35fb498c218d959841dcdfa835ff92ef3a8dd1ed7f3e84590f53",
    "cookies": "b13ab3f6a59045b8ca7031e0032618280b3d49749902d1f255a1d0c5ce9de066"
},
"errors": {
    "html": null,
    "png": null,
    "navigate": null
},
"png": "https://s3.amazonaws.com/geoscreenshot-static/fabd8fa3-c4aa-4a0f-9894-a3580b31ec74.png",
"html": "https://s3.amazonaws.com/geoscreenshot-static/fabd8fa3-c4aa-4a0f-9894-a3580b31ec74.html",
"console": "https://s3.amazonaws.com/geoscreenshot-static/fabd8fa3-c4aa-4a0f-9894-a3580b31ec74.console.json",
"har": "https://s3.amazonaws.com/geoscreenshot-static/fabd8fa3-c4aa-4a0f-9894-a3580b31ec74.har.json",
"metrics": {
    "dnsLookup": 0,
    "tcpConnect": 0,
    "request": 175,
    "response": 917,
    "domLoaded": 3859,
    "domInteractive": 1910,
    "pageLoad": 1,
    "fullTime": 4821
},
"cookies": "https://s3.amazonaws.com/geoscreenshot-static/fabd8fa3-c4aa-4a0f-9894-a3580b31ec74.cookies.json",
"ip": "69.197.157.130",
"title": "Google News",
"capture_id": "148936",
"domain": "news.google.com",
"url": "https://news.google.com",
"metro_id": "us_mss_knsscty",
"node_id": "us_mss_kns_1luhIL",
"options": "{}",
"created_at": "2020-06-08T10:10:21.000Z",
"updated_at": "2020-06-08T10:10:21.000Z"
}

GET Query Parameters

Parameter Required Default Description
apikey Required None API key from Dashboard
url Required None A valid URL that starts with either http:// or https://
country Required Random A valid country code https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements
metro_id Optional Random Metro ID Specific metropolitan area, can be fetched from the following public endpoint; https://api.geoscreenshot.com/location
node_id Optional Random Node ID Specific VPS node for capture, can also be fetched from the locations endpoint. Alternatively, it can be found on a detailed location page such as the following: https://www.geoscreenshot.com/country/south-africa/cape-town-western-cape
user_agent Optional Google Chrome Complete user agent string
full_page Optional 0 Capture the full height of the page
delay Optional 5s Delay after page load before capturing screenshot (seconds)
width Optional 1280 Viewport width
height Optional 1024 Viewport height
local_tz Optional 1 Sets the browser's timezone to the location
local_html5_geolocation Optional 1 Sets the browsers' HTML5 geolocation API values to the location's lat/lng

JSON description

Key Description
_meta Metadata about the capture request lifecycle
_hash Hashes of the data returned, including a perceptual hash for similarity indexing
errors Any errors encountered during capture
png URL to the PNG
html URL to the rendered HTML
console A JSON of any console messages encountered
har HTTP archive waterfall of the requests
metrics Page load performance metrics
cookies Cookie jar JSON
ip The public IP used
title The webpage’s final title at the time of the capture
capture_id Internal id used for future reference
domain The parsed domain of the URL, used for blacklisting adult sties
url The requested URL
metro_id The precise metropolitan area used. You can pass this instead of country to get consistent geo-ip targeting.
node_id The precise VPS node used to run the capture. You can pass this instead of metro_id to re-use the same IP multiple times

All Locations

The location endpoint provides the latest information on available capture locations. GeoScreenshot supports 3 levels of granularity for specifying locations:

Type Key Stability Description
Country country_code or country Highest A random GeoIP from a country
Metro metro_id High A random GeoIP from a pool of GeoIPs for a metro area (a 50 mile radius)
Node node_id Medium A stable set of GeoIPs from a specific node.

We recommend using country or metro_id for superior redundency as nodes can occasionally go down.

Get a JSON of all the available locations. 

curl "https://api.geoscreenshot.com/location"

A successful response will return the following JSON format

{
   "total":300,
   "limit":1000,
   "skip":0,
   "data":[
      {
         "id":1,
         "metro_id":"gh_grt_ccr",
         "node_id":null,
         "slug":"accra-greater-accra",
         "city":"Accra",
         "latitude":5.5500349998,
         "longitude":-0.2167160064,
         "pop":2042132,
         "country":"Ghana",
         "country_code":"GH",
         "iso3":null,
         "state":"Greater Accra",
         "tier":3,
         "granularity":"city",
         "state_code":"AA",
         "nodes":[
            {
               "node_id":"gh_grt_ccr_ZnUpEA",
               "city":"Accra",
               "latitude":5.5557198524,
               "longitude":-0.1963060051,
               "id":1
            }
         ],
         "total":1,
         "country_meta":{
            "slug":"ghana",
            "latlng":[
               8,
               -2
            ]
         }
      },
      {
         "id":2,
         "metro_id":"us_nwy_lbny",
         "node_id":null,
         "slug":"albany-new-york",
         "city":"Albany",
         "latitude":42.6700172424,
         "longitude":-73.8199462891,
         "pop":484286,
         "country":"United States of America",
         "country_code":"US",
         "iso3":null,
         "state":"New York",
         "tier":3,
         "granularity":"city",
         "state_code":"NY",
         "nodes":[
            {
               "node_id":"us_nwy_lth_ZPf9YC",
               "city":"Latham",
               "latitude":42.7453994751,
               "longitude":-73.7592010498,
               "id":2
            }
         ],
         "total":1,
         "country_meta":{
            "slug":"united-states-of-america",
            "latlng":[
               38,
               -97
            ]
         }
      }
   ]
}

Search Locations

GET Query Parameters

Parameter Description
metro_id Metro ID
node_id Node ID
country_code A valid country code https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements
city URL-escaped city name, for example: new%20york 
curl "https://api.geoscreenshot.com/location?country_code=kz"

A successful response will return the following JSON format

{
   "total":2,
   "limit":1000,
   "skip":0,
   "data":[
      {
         "id":111,
         "metro_id":"kz_qrg_qrghndy",
         "node_id":null,
         "slug":"qaraghandy-qaraghandy",
         "city":"Qaraghandy",
         "latitude":49.8849754333,
         "longitude":73.1150131226,
         "pop":378274,
         "country":"Kazakhstan",
         "country_code":"KZ",
         "iso3":null,
         "state":"Qaraghandy",
         "tier":3,
         "granularity":"city",
         "state_code":"KAR",
         "nodes":[
            {
               "node_id":"kz_krg_krg_ZDCfgY",
               "city":"Karaganda",
               "latitude":49.8119010925,
               "longitude":73.0969009399,
               "id":109
            }
         ],
         "total":1,
         "country_meta":{
            "slug":"kazakhstan",
            "latlng":[
               48,
               68
            ]
         }
      },
      {
         "id":387,
         "metro_id":"kz_random",
         "node_id":null,
         "slug":"random-",
         "city":"Random",
         "latitude":51.1811256409,
         "longitude":71.427772522,
         "pop":335313,
         "country":"Kazakhstan",
         "country_code":"KZ",
         "iso3":null,
         "state":"",
         "tier":2,
         "granularity":"country",
         "state_code":"AST",
         "nodes":[
            {
               "node_id":"kz_nrs_nrs_21hL3N",
               "city":"Nur-Sultan",
               "latitude":51.1604995728,
               "longitude":71.4703979492,
               "id":380
            }
         ],
         "total":1,
         "country_meta":{
            "slug":"kazakhstan",
            "latlng":[
               48,
               68
            ]
         }
      }
   ]
}

Errors

The GeoScreenshot API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid. Make sure you are passing valid values for the paramaters.
401 Unauthorized -- Your API key is wrong.
404 Not Found -- Make sure your URL is properly constructed.
500 Internal Server Error -- We had a problem with our server. Try again later. Please contact support at contact@geoscreenshot.com
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.
http