Get a list of cities by state

This function is currently only available in Brazil. With the Geocode API you can get a list of cities in the state you want. To do this, you need to make a POST request to the following endpoint:

The term {{state}} must be replaced by the acronym (UF) of the desired state. Example:

The response will be returned as follows:

    "found": 645,
    "results": [
            "address": {
                "city": "AGUAÍ",
                "state": {
                    "code": "SP",
                    "name": "SÃO PAULO"
                "country": "BRASIL",
                "capital": false,
                "area": 474.695,
                "ibge": {
                    "city": "3500303",
                    "state": "35"
                "mainLocation": {
                    "lat": -22.0589929,
                    "lon": -46.9822351
                "leftZipCode": "13860001",
                "rightZipCode": "13869999"
            "type": "CITY",
            "score": 52.155304,
            "label": "AGUAÍ, SP, BRASIL"

The following information will be returned:

  • found – Number of cities returned;
  • results – Array of objects with results found:
    • address – Object with city information:
      • city – Name of city;
      • state – Object with state-related data:
        • code – State acronym;
        • name – Name of state;
      • country – Country;
      • capital – Boolean value indicating whether the city is the state capital;
      • area – Total area of the city, in square meters;
      • ibge – Object with city and state IBGE codes:
        • city – City’s IBGE code;
        • state – State’s IBGE code;
      • mainLocation – Object with geographical coordinates in latitude/longitude:
        • lat – Latitude in decimal degrees;
        • lon – Longitude in decimal degrees;
      • leftZipCode – First zip code in the city’s zip code range;
      • rightZipCode – Last zip code in the city’s zip code range;
    • type – Indicates the best element found in the map base for returning the geographic coordinate. In this case it will always be returned as “CITY”;
    • score – Reference score for the result of the geocoding process;
    • label – Complete address found used in the geocoding process. In this case, it will always be returned as “City, State, Country”.