RTB API

Using merchenta.io for real-time bidding

Geo metadata 

We often get asked to provide metadata useful in other APIs (e.g. campaign setup). The endpoints listed below provide all the values which can be used for setting up geo targeting. Due to API validation, only values returned by these endpoints are accepted in other APIs. Attempting to use any other value will not pass validation.

Note Please use these services very carefully because of the huge amount of data which is returned. We suggest you consider a caching mechanism on the client side to save time and bandwidth for the data transfer.

Countries list 

Gets the world’s countries list.

/v3/metadata/geo/countries
  • Curl
  • Copy
    curl -i \ -X GET \ -H 'Authorization: Bearer {YOUR_TOKEN_HERE}' \ https://sandbox.rtbapi.io/v3/metadata/geo/countries
  • Response  200
  • Headers
    Content-Type: application/json
    Schema
    {
        "type": "array",
        "items": {
            "type": "object",
            "properties": {
                "countryCode": {
                    "type": "string"
                },
                "countryName": {
                    "type": "string"
                },
                "regionName": {
                    "type": "string"
                }
            }
        }
    }
    
    Example body
    {
        "status": "success",
        "data": {
            "countries": [
                {
                    "countryCode": "AF",
                    "countryName": "Afghanistan, Islamic Republic of",
                    "regionName": "Asia"
                },
                {
                    "countryCode": "PA",
                    "countryName": "Panama, Republic of",
                    "regionName": "North America"
                }
            ]
        }
    }

U.S. states list 

Gets the U.S. states list in ISO-3166-2 format with state abbreviation prefixed with United States’ country code (US).

/v3/metadata/geo/states
  • Curl
  • Copy
    curl -i \ -X GET \ -H 'Authorization: Bearer {YOUR_TOKEN_HERE}' \ https://sandbox.rtbapi.io/v3/metadata/geo/states
  • Response  200
  • Headers
    Content-Type: application/json
    Schema
    {
        "type": "array",
        "items": {
            "type": "object",
            "properties": {
                "stateCode": {
                    "type": "string"
                },
                "stateName": {
                    "type": "string"
                }
            }
        }
    }
    
    Example body
    {
        "status": "success",
        "data": {
            "countries": [
                {
                    "stateCode": "US-CT",
                    "stateName": "Connecticut"
                },
                {
                    "stateCode": "US-DE",
                    "stateName": "Delaware"
                }
            ]
        }
    }

Cities list 

Gets the world’s cities list.

Note

Because of the huge amount of returned data (more than 400 000 entries) use this endpoint with special care.

/v3/metadata/geo/cities
  • Parameters
  • countries
    string (optional) Example: US,PL

    The response only contains cities from given country codes. Each code is separated by a comma.

  • Curl
  • Copy
    curl -i \ -X GET \ -H 'Authorization: Bearer {YOUR_TOKEN_HERE}' \ https://sandbox.rtbapi.io/v3/metadata/geo/cities
  • Response  200
  • Headers
    Content-Type: application/json
    Schema
    {
        "type": "array",
        "items": {
            "type": "object",
            "properties": {
                "city": {
                    "type": "string"
                },
                "countryCode": {
                    "type": "string"
                }
            }
        }
    }
    
    Example body
    {
        "status": "success",
        "data": {
            "cities": [
                {
                    "city": "Windsor",
                    "countryCode":"CA"
                },
                {
                    "city": "Regina",
                    "countryCode":"CA"
                }
            ]
        }
    }

U.S. ZIP codes list 

Gets the U.S. ZIP codes list.

/v3/metadata/geo/zipCodes
  • Curl
  • Copy
    curl -i \ -X GET \ -H 'Authorization: Bearer {YOUR_TOKEN_HERE}' \ https://sandbox.rtbapi.io/v3/metadata/geo/zipCodes
  • Response  200
  • Headers
    Content-Type: application/json
    Schema
    {
        "type": "array",
        "items": {
            "type": "object",
            "properties": {
                "zipCode": {
                    "type": "string"
                },
                "primaryCity": {
                    "type": "string"
                },
                "state": {
                    "type": "string"
                }
            }
        }
    }
    
    Example body
    {
        "status": "success",
        "data": {
            "zipCodes": [
                {
                    "zipCode": "50241",
                    "primaryCity": "Saint Marys",
                    "state": "IA"
                },
                {
                    "zipCode": "52201",
                    "primaryCity": "Ainsworth",
                    "state":"IA"
                }
            ]
        }
    }

ZIP code 

Checks whether given ZIP code exists and returns it when available.

/v3/metadata/geo/zipCodes/{zipCodeId}
  • Parameters
  • zipCodeId
    string (required) Example: 50241

    The zip code

  • Curl
  • Copy
    curl -i \ -X GET \ -H 'Authorization: Bearer {YOUR_TOKEN_HERE}' \ https://sandbox.rtbapi.io/v3/metadata/geo/zipCodes/50241
  • Response  200
  • Headers
    Content-Type: application/json
    Schema
    {
        "type": "object",
        "properties": {
            "zipCode": {
                "type": "string"
            },
            "primaryCity": {
                "type": "string"
            },
            "state": {
                "type": "string"
            }
        }
    }
    
    Example body
    {
        "status": "success",
        "data": {
            "zipCode":
                {
                    "zipCode": "50241",
                    "primaryCity": "Saint Marys",
                    "state": "IA"
                }
        }
    }
  • Response  404

DMA codes list 

Gets the list of DMA codes.

/v3/metadata/geo/dmaCodes
  • Curl
  • Copy
    curl -i \ -X GET \ -H 'Authorization: Bearer {YOUR_TOKEN_HERE}' \ https://sandbox.rtbapi.io/v3/metadata/geo/dmaCodes
  • Response  200
  • Headers
    Content-Type: application/json
    Schema
    {
        "type": "array",
        "items": {
            "type": "object",
            "properties": {
                "dmaCode": {
                    "type": "number"
                },
                "dmaRegion": {
                    "type": "string"
                }
            }
        }
    }
    
    Example body
    {
        "status": "success",
        "data": {
            "dmaCodes": [
                {
                    "dmaCode": 662,
                    "dmaRegion": "ABILENE-SWEETWATER"
                },
                {
                    "dmaCode": 525,
                    "dmaRegion": "ALBANY"
                }
            ]
        }
    }

DMA code 

Checks whether given DMA code exists and returns it when available.

/v3/metadata/geo/dmaCodes/{dmaCodeId}
  • Parameters
  • dmaCodeId
    string (required) Example: 825

    The DMA code

  • Curl
  • Copy
    curl -i \ -X GET \ -H 'Authorization: Bearer {YOUR_TOKEN_HERE}' \ https://sandbox.rtbapi.io/v3/metadata/geo/dmaCodes/825
  • Response  200
  • Headers
    Content-Type: application/json
    Schema
    {
        "type": "object",
        "properties": {
            "dmaCode": {
                "type": "number"
            },
            "dmaRegion": {
                "type": "string"
            }
        }
    }
    
    Example body
    {
        "status": "success",
        "data": {
            "dmaCode": {
                "dmaCode": 825,
                "dmaRegion": "SAN DIEGO"
            }
        }
    }
Next page  Previous page