Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Updated per TW-1029

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

Warning

Before using PubMatic APIs, first generate the API Token. For more information, refer to ; see Getting Started with PubMatic APIs

Overview

...

.

Request

         

URIhttp://{domainName}/common/geo?pageSize=20&pageNumber=1
HTTP MethodGET

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
pageNumberIntegerOptional

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

pageSizeIntegerOptional

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

Response

...

Response Headers

...


Response
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

Code Block
languagejs
linenumberstrue
{

    "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

Type

Description

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

Type

Description

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

country

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

countryCode

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.

geoLevelId

String

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.

region

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".

uri

String

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.

Filters

The following table details the available Geo filter parameters:

FilterDescription
countryCode

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

geoLevel

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

  • COUNTRY
  • CITY
nameSearch criteria; for example, name%20like%20*spain*.

Sorting

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
Code Block
languagejs
linenumberstrue
/*
*  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 'https://api.pubmatic.com/v1/common/geo?filters=name%20like%20*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
    }
}