Retrieve a List of Geos

This API allows you to retrieve the list of all Geos in the PubMatic platform.

Before using PubMatic APIs, first generate the API Token; see Getting Started with PubMatic APIs.



Request Headers

Header NameTypeValueRequiredDescription
AuthorizationStringBearer ${access_token}YesNeed to send the access token generating for authentication at the place of ${access_token}.
For more information about access tokens, refer to Getting Started with PubMatic APIs.

Request Query Parameters

Parameter NameTypeRequiredDescription

Page number to be fetched in case of multiple pages.
Its default value is 1.


Maximum number of rows to be included in the response.
Its default value is 100.

filterStringOptionalFilter the response based on provided criteria (see example below)
sortStringOptionalSort the response by field(s)


Header NameType
Content-type application/json

Response Body

Response Body ParameterTypeDescription
metaDataObjectPagination details
geoIdIntegerUnique identifier for the geo.
nameStringName of the geo.
countryCodeStringCountry code for the geo.
dmaCodeIntegerDMA code for the geo.
geoLevelStringLevel of the geo. Possible values are CITY and COUNTRY.

Sample Response JSON


    "metaData": {
        "startIndex": 1,
        "request": {
            "pageSize": 3,
            "pageNumber": 1
        "totalRecords": 162910,
        "endIndex": 3
    "items": [
            "geoId": 0,
            "name": "Rest Of The World",
            "countryCode": "",
            "dmaCode": 0,
            "geoLevel": "COUNTRY"
            "geoId": 1,
            "name": "Anonymous Proxy",
            "countryCode": "A1",
            "dmaCode": 0,
            "geoLevel": "COUNTRY"
            "geoId": 2,
            "name": "Satellite Provider",
            "countryCode": "A2",
            "dmaCode": 0,
            "geoLevel": "COUNTRY"

Filtering and sorting the response

The Geo API provides filtering and sorting parameters to narrow results when you are looking for a very specific or set of specific geo details. The response has the following header, along with the response body parameters.

Response Header Name



Content-type application/jsonA JSON payload made up of the response body parameters below to report the results of the request; see example JSON response below.

Response Body Parameter



cityStringName of a city; for example, "city": "Barcelona".


StringName of a country; for example, "country": "Spain".


StringUnique country code for geo; for example, "countryCode": "ES".
dmaCodeIntegerA Nielsen Designated Market Area code derived from your original request parameters; for exampley, "dmaCode": 0. Note that dmaCode is not returned in all cases.
geoLevelStringThe geoLevel you specified in the request; either, COUNTRY or CITY.



Integer code for the geoLevel scope you defined in the request (country or city). May be one of the following:

  • 1 = Country
  • 3 = City
idIntegerUnique identifier for a geo; for example, "id": 275439.
nameStringThe name of the geo. The result depends upon the request scope determined by the filters you apply. For example, if you filter for results pertaining only to "Barcelona," then name returned is, "name": "Barcelona". But if your filter includes all of Spain, then the name returned is, "name": "Spain". See example JSON response below.


StringThe name of the region as determined by the value you supplied in the request; for example, if geoLevel scope is CITY, countryCode is ES, and city was Barcelona, then region will be, "region": "Barcelona". See example JSON response below.
regionCodeStringAn abbreviated code representing the scope of the region determined by your request parameters; for example, you may see "regionCode": "CA", when your request targets the US state of California. But if your request targets a much narrower scope, such as a CITY, then in the case of Barcelona, the response may contain, "regionCode": "B".



The PubMatic internal URI that generated the response; for example, http://api-mgmt.sfo.pubmatic.local/v1/common/geo/275439. Note that this may not match the URI of your original API call.

metaDataObjectPagination details; see example JSON response below.


The following table details the available Geo filter parameters:


Use to limit the search to a specific country code (ISO 2 characters); for example, filters=countryCode%20eq%20ES.


Use to set the response scope to one of the following:

  • 1 (Country)
  • 2 (Region)
  • 3 (City)
nameSearch criteria; for example, name%20like%20*spain*.


In addition to filtering query results, you can also use the sort parameter in your request to sort the response on fields that make send for you; for example, sort=geoLevel,name. See the sample call with JSON response below.

Example call with filtered and sorted response
*  CURL call that sorts the response with: sort=geoLevel,name. Note that <API_KEY> at the thend of the call represents your generated PubToken used to authenticate your call with PubMatic; see Getting Started with PubMatic APIs.
curl '*celona*&sort=geoLevel,name&hideInvalid=true&pageNumber=1&pageSize=100&filters=geoLevel%20eq%203&filters=countryCode%20eq%20ES' -H 'Authorization:Bearer <API_KEY>' 

// JSON payload response
    "items": [
            "city": "Barcelona",
            "country": "Spain",
            "countryCode": "ES",
            "geoLevel": "CITY",
            "geoLevelId": 3,
            "id": 275439,
            "name": "Barcelona",
            "region": "Barcelona",
            "regionCode": "B",
            "uri": "http://api-mgmt.sfo.pubmatic.local/v1/common/geo/275439"
    "metaData": {
        "endIndex": 1,
        "startIndex": 1,
        "totalRecords": 1

⇧ Top

Do you have feedback on this document? Let us know: email us.

Table of Contents