Why

Have you ever found yourself in the situation of needing a geojson from the France divided by Regions?

Well, maybe not that specific case... but with this API you can replace France by the country of your choosing, and doing a simple API call you will have the solution that you need for your project.

You could need something more specific, like the state of New York divided by counties, same thing, one simple query will be enough.

Introduction

A simple API to get any geometry(almost all) of the world. With RESTGIS you will be able to get a collection of geographic data(aka map) in different formats like Geojson, Topojson, SVG among others.

Authentication

Access to the API is allowed by using an API KEY. You can get one after you register and create the request.

Authenticated requests must include a x-api-key header containing the API KEY that you requested.

Be sure to keep your API keys secure. Do not share them in publicly accessible areas such as GitHub, client-side code, and so forth.

Also note that all API requests must be made over HTTPS. Calls made over plain HTTP will attempt to be automatically upgraded to HTTPS, though this use cases is discouraged.

Caching

All endpoints will cache any request for 24 hours since the data will not likely change. The Expires header will let you know when the cache for that request will expire.

Rate Limits

API requests may be rate limited depending on your subscription plan and traffic patterns.

The following response headers will be present in these cases:

• x-ratelimit-limit

  • The maximum number of requests that the consumer is permitted to make.

• x-ratelimit-remaining

  • The number of requests remaining in the current rate limit window.

• x-ratelimit-reset

  • The time at which the current rate limit window resets in UTC epoch seconds.

When the rate limit is exceeded, an error is returned with the status "429 Too Many Requests":

{
  "error": {
    "code": "too_many_requests",
    "message": "The request exceeded your daily limit rate.
    You will have to wait for {number} seconds."
  }
}

Errors

• 400 - BAD REQUEST

  • Your request is invalid.

• 401 - UNAUTHORIZED

  • Your API key is missing or wrong.

• 404 - NOT FOUND

  • No matching word was found.

• 500 - INTERNAL SERVER ERROR

  • We had a problem with our server. Try again later.

Pagination

All endpoints will have a mandatory pagination. The maximum items per page are 30.

You are able to navigate between pages. Every response will contain the following pagination headers:

page            The current page number.
pageSize        The size of the pagination that you are currently using, defaults to 30.
totalRecords    The amount of records in all pages.
totalPages      The amount of total pages, this is defined as totalRecords / pageSize.

You can change the pagination size and navigate through the pages by sending optional query params:

?page={page_number}&pageSize={page_size_number}

Resolution

All endpoints provide a way to get more or less detailed versions of the same features by setting the optional resolution query parameter:

?resolution={resolution_number}

This value goes from 0.01 to 1. The default is 0.05.

Path

This endpoint will retrieve a set of features according to the specified hierarchy path.

/v1/path/{admin_level_0}/{?admin_level_1}/{?admin_leve_2}/{?admin_leve_3}/...

Examples

/v1/path/United States                  Will retrieve the geometries for USA
/v1/path/United States/New York         Will provide the geometries for New York
/v1/path/United States?admin_level=1    Will return all the states for USA

Optional parameters

• center: boolean

  • default: False

  • This parameter will let you get the contour of the feature or just the geographical center of it.

• properties: Array

  • default: id,name,lat,lng,bounds

  • This parameter will let you enrich the properties parameter of a given geometry.

  • Available values:

    • id: Unique identifier

    • name: Geometry name (Country name, State/Provice name, etc)

    • full_name: Full concatenated name, for ex: New York, United States

    • lat: Latitude of the center of the geometry

    • lng: Longitude of the center of the geometry

    • bounds: Bounding box of the geometry in lat,lng

    • Only available for countries or administrative level zero:

      • area: Area in square meters
      • population: Population
      • alpha2: Only for countries, alpha2 identifier
      • alpha3: Only for countries, alpha3 identifier
      • borders: Array of alpha3 codes of border countries
      • translations: Dictionary with key as alpha2 and the name in that country language
      • demonym: The demonym on gentilic for the given country
      • native_name: The name used locally for that country
      • alt_spellings: Alternative names for the country

• admin_level: number

  • default: 0
  • This parameter can be used to get the desired division of the current geometry.
  • Defaults to 0, meaning that you will get the base administrative level of the selected geographical feature.
  • Setting admin_level=1 will return the first administrative division of the selected geometry (if available).

Also check Pagination, Resolution

Responses

• Status 200 - OK

{
    "type": "FeatureCollection",
    "features": [
        ...
        {
            "type": "Feature",
            "geometry": { ... },
            "properties": {
                "id": "USA",
                "name": "United States",
                ...
            }
        }
    ]
}

• Status 400, 404, 500:

  • See Errors

• Status 401:

  • See Authentication

Name

This endpoint will retrieve a set of features according to the specified name.

/v1/name/{name}

Examples

/v1/name/United States      Will retrieve the geometries for USA
/v1/name/New York           Will provide the geometries for New York

Optional parameters

• center: boolean

  • default: False

  • This parameter will let you get the contour of the feature or just the geographical center of it.

• properties: Array

  • default: id,name,lat,lng,bounds

  • This parameter will let you enrich the properties parameter of a given geometry.

  • Available values:

    • id: Unique identifier

    • name: Geometry name (Country name, State/Provice name, etc)

    • full_name: Full concatenated name, for ex: New York, United States

    • lat: Latitude of the center of the geometry

    • lng: Longitude of the center of the geometry

    • bounds: Bounding box of the geometry in lat,lng

    • Only available for countries or administrative level zero:

      • area: Area in square meters
      • population: Population
      • alpha2: Only for countries, alpha2 identifier
      • alpha3: Only for countries, alpha3 identifier
      • borders: Array of alpha3 codes of border countries
      • translations: Dictionary with key as alpha2 and the name in that country language
      • demonym: The demonym on gentilic for the given country
      • native_name: The name used locally for that country
      • alt_spellings: Alternative names for the country

• admin_level: number

  • default: 0
  • This parameter can be used to get the desired division of the current geometry.
  • Defaults to 0, meaning that you will get the base administrative level of the selected geographical feature.
  • Setting admin_level=1 will return the first administrative division of the selected geometry (if available).

Also check Pagination, Resolution

Responses

• Status 200 - OK

{
    "type": "FeatureCollection",
    "features": [
        ...
        {
            "type": "Feature",
            "geometry": { ... },
            "properties": {
                "id": "USA",
                "name": "United States",
                ...
            }
        }
    ]
}

• Status 400, 404, 500:

  • See Errors

• Status 401:

  • See Authentication

Lat Lng

This endpoint will retrieve a set of features according to the specified lat-lng bounding box.

/v1/lat-lng/{lat_min}/{lat_max}/{lng_min}/{lng_max}/

Examples

/v1/lat-lng/0/90/-180/180      Will retrieve the admin_level_0 geometries (countries) for the northern emisphere.

Optional parameters

• center: boolean

  • default: False

  • This parameter will let you get the contour of the feature or just the geographical center of it.

• properties: Array

  • default: id,name,lat,lng,bounds

  • This parameter will let you enrich the properties parameter of a given geometry.

  • Available values:

    • id: Unique identifier

    • name: Geometry name (Country name, State/Provice name, etc)

    • full_name: Full concatenated name, for ex: New York, United States

    • lat: Latitude of the center of the geometry

    • lng: Longitude of the center of the geometry

    • bounds: Bounding box of the geometry in lat,lng

    • Only available for countries or administrative level zero:

      • area: Area in square meters
      • population: Population
      • alpha2: Only for countries, alpha2 identifier
      • alpha3: Only for countries, alpha3 identifier
      • borders: Array of alpha3 codes of border countries
      • translations: Dictionary with key as alpha2 and the name in that country language
      • demonym: The demonym on gentilic for the given country
      • native_name: The name used locally for that country
      • alt_spellings: Alternative names for the country

• admin_level: number

  • default: 0
  • This parameter can be used to get the desired division of the current geometry.
  • Defaults to 0, meaning that you will get the base administrative level of the selected geographical feature.
  • Setting admin_level=1 will return the first administrative division of the selected geometry (if available).

Also check Pagination, Resolution

Responses

• Status 200 - OK

{
    "type": "FeatureCollection",
    "features": [
        ...
        {
            "type": "Feature",
            "geometry": { ... },
            "properties": {
                "id": "USA",
                "name": "United States",
                ...
            }
        }
    ]
}

• Status 400, 404, 500:

  • See Errors

• Status 401:

  • See Authentication

Countries - Alpha2

This endpoint will retrieve a set of features according to the specified alpha2 code.

/v1/country/alpha2/{alpha2}

Examples

/v1/country/alpha2/US      Will retrieve the geometries for United States
/v1/country/alpha2/ES      Will provide the geometries for Spain

Optional parameters

• center: boolean

  • default: False

  • This parameter will let you get the contour of the feature or just the geographical center of it.

• properties: Array

  • default: id,name,lat,lng,bounds

  • This parameter will let you enrich the properties parameter of a given geometry.

  • Available values:

    • id: Unique identifier

    • name: Geometry name (Country name, State/Provice name, etc)

    • full_name: Full concatenated name, for ex: New York, United States

    • lat: Latitude of the center of the geometry

    • lng: Longitude of the center of the geometry

    • bounds: Bounding box of the geometry in lat,lng

    • Only available for countries or administrative level zero:

      • area: Area in square meters
      • population: Population
      • alpha2: Only for countries, alpha2 identifier
      • alpha3: Only for countries, alpha3 identifier
      • borders: Array of alpha3 codes of border countries
      • translations: Dictionary with key as alpha2 and the name in that country language
      • demonym: The demonym on gentilic for the given country
      • native_name: The name used locally for that country
      • alt_spellings: Alternative names for the country

• admin_level: number

  • default: 0
  • This parameter can be used to get the desired division of the current geometry.
  • Defaults to 0, meaning that you will get the base administrative level of the selected geographical feature.
  • Setting admin_level=1 will return the first administrative division of the selected geometry (if available).

Also check Pagination, Resolution

Responses

• Status 200 - OK

{
    "type": "FeatureCollection",
    "features": [
        ...
        {
            "type": "Feature",
            "geometry": { ... },
            "properties": {
                "id": "USA",
                "name": "United States",
                ...
            }
        }
    ]
}

• Status 400, 404, 500:

  • See Errors

• Status 401:

  • See Authentication

Countries - Alpha3

This endpoint will retrieve a set of features according to the specified alpha3 code.

/v1/country/alpha3/{alpha3}

Examples

/v1/country/alpha3/US      Will retrieve the geometries for United States
/v1/country/alpha3/ESP     Will provide the geometries for Spain

Optional parameters

• center: boolean

  • default: False

  • This parameter will let you get the contour of the feature or just the geographical center of it.

• properties: Array

  • default: id,name,lat,lng,bounds

  • This parameter will let you enrich the properties parameter of a given geometry.

  • Available values:

    • id: Unique identifier

    • name: Geometry name (Country name, State/Provice name, etc)

    • full_name: Full concatenated name, for ex: New York, United States

    • lat: Latitude of the center of the geometry

    • lng: Longitude of the center of the geometry

    • bounds: Bounding box of the geometry in lat,lng

    • Only available for countries or administrative level zero:

      • area: Area in square meters
      • population: Population
      • alpha2: Only for countries, alpha2 identifier
      • alpha3: Only for countries, alpha3 identifier
      • borders: Array of alpha3 codes of border countries
      • translations: Dictionary with key as alpha2 and the name in that country language
      • demonym: The demonym on gentilic for the given country
      • native_name: The name used locally for that country
      • alt_spellings: Alternative names for the country

• admin_level: number

  • default: 0
  • This parameter can be used to get the desired division of the current geometry.
  • Defaults to 0, meaning that you will get the base administrative level of the selected geographical feature.
  • Setting admin_level=1 will return the first administrative division of the selected geometry (if available).

Also check Pagination, Resolution

Responses

• Status 200 - OK

{
    "type": "FeatureCollection",
    "features": [
        ...
        {
            "type": "Feature",
            "geometry": { ... },
            "properties": {
                "id": "USA",
                "name": "United States",
                ...
            }
        }
    ]
}

• Status 400, 404, 500:

  • See Errors

• Status 401:

  • See Authentication

Countries - Region

This endpoint will retrieve a set of features according to the specified region.

/v1/region/{region}

Examples

/v1/region/Europe      Will retrieve the geometries for all the countries in Europe.

Optional parameters

• center: boolean

  • default: False

  • This parameter will let you get the contour of the feature or just the geographical center of it.

• properties: Array

  • default: id,name,lat,lng,bounds

  • This parameter will let you enrich the properties parameter of a given geometry.

  • Available values:

    • id: Unique identifier

    • name: Geometry name (Country name, State/Provice name, etc)

    • full_name: Full concatenated name, for ex: New York, United States

    • lat: Latitude of the center of the geometry

    • lng: Longitude of the center of the geometry

    • bounds: Bounding box of the geometry in lat,lng

    • Only available for countries or administrative level zero:

      • area: Area in square meters
      • population: Population
      • alpha2: Only for countries, alpha2 identifier
      • alpha3: Only for countries, alpha3 identifier
      • borders: Array of alpha3 codes of border countries
      • translations: Dictionary with key as alpha2 and the name in that country language
      • demonym: The demonym on gentilic for the given country
      • native_name: The name used locally for that country
      • alt_spellings: Alternative names for the country

• admin_level: number

  • default: 0
  • This parameter can be used to get the desired division of the current geometry.
  • Defaults to 0, meaning that you will get the base administrative level of the selected geographical feature.
  • Setting admin_level=1 will return the first administrative division of the selected geometry (if available).

Also check Pagination, Resolution

Responses

• Status 200 - OK

{
    "type": "FeatureCollection",
    "features": [
        ...
        {
            "type": "Feature",
            "geometry": { ... },
            "properties": {
                "id": "USA",
                "name": "United States",
                ...
            }
        }
    ]
}

• Status 400, 404, 500:

  • See Errors

• Status 401:

  • See Authentication

Countries - Subregion

This endpoint will retrieve a set of features according to the specified subregion.

/v1/subregion/{subregion}

Examples

/v1/subregion/North America      Will retrieve the geometries for all the countries in North America.

Optional parameters

• center: boolean

  • default: False

  • This parameter will let you get the contour of the feature or just the geographical center of it.

• properties: Array

  • default: id,name,lat,lng,bounds

  • This parameter will let you enrich the properties parameter of a given geometry.

  • Available values:

    • id: Unique identifier

    • name: Geometry name (Country name, State/Provice name, etc)

    • full_name: Full concatenated name, for ex: New York, United States

    • lat: Latitude of the center of the geometry

    • lng: Longitude of the center of the geometry

    • bounds: Bounding box of the geometry in lat,lng

    • Only available for countries or administrative level zero:

      • area: Area in square meters
      • population: Population
      • alpha2: Only for countries, alpha2 identifier
      • alpha3: Only for countries, alpha3 identifier
      • borders: Array of alpha3 codes of border countries
      • translations: Dictionary with key as alpha2 and the name in that country language
      • demonym: The demonym on gentilic for the given country
      • native_name: The name used locally for that country
      • alt_spellings: Alternative names for the country

Also check Pagination, Resolution

Responses

• Status 200 - OK

{
    "type": "FeatureCollection",
    "features": [
        ...
        {
            "type": "Feature",
            "geometry": { ... },
            "properties": {
                "id": "USA",
                "name": "United States",
                ...
            }
        }
    ]
}

• Status 400, 404, 500:

  • See Errors

• Status 401:

  • See Authentication

User - Custom Maps

This endpoint will retrieve a set of features according to the specified map.

/v1/custom-map/{mapId}

Examples

/v1/custom-map/65c958f9-8f4e-4322-bcf2-4a21b2ae45b3      Will retrieve the features for the specified map id.

Also check Pagination, Resolution

Responses

• Status 200 - OK

{
    "type": "FeatureCollection",
    "features": [
        ...
        {
            "type": "Feature",
            "geometry": { ... },
            "properties": {
                "id": "USA",
                "name": "United States",
                ...
            }
        }
    ]
}

• Status 400, 404, 500:

  • See Errors

• Status 401:

  • See Authentication