Mapbox Search Geocoding Get Forward

1 credits/call
ae_mapbox_search_geocoding_get_forward

Convert a place name or address into geographic coordinates.

Maps
1 credits/call

Pricing

1 credits/call
ConditionCharge
Each call1 credits/call

Parameters

Optional parameters use the platform defaults when omitted.

ParameterTypeRequiredDescriptionDefault
qstringYesThe feature you're trying to look up. This could be an address, a city name, etc. The search text should be expressed as a URL-encoded UTF-8 string, and must not contain the semicolon character. Your search text, once decoded, must consist of at most 20 words and numbers separated by spacing and punctuation, and at most 256 characters.—
bboxstringNoLimit results to only those contained within the supplied bounding box. Bounding boxes should be supplied as four numbers separated by commas, in minLon,minLat,maxLon,maxLat order. The bounding box cannot cross the 180th meridian.—
blockstringNoIn some countries like Japan, the block is a component in the address.—
limitintegerNoSpecify the maximum number of results to return. The default is 5 and the maximum supported is 10.—
placestringNoTypically these are cities, villages, municipalities, etc.—
typesstringNoFilter results to include only a subset (one or more) of the available feature types. Options are country, region, postcode, district, place, locality, neighborhood, street, and address. Multiple options can be comma-separated.—
formatenum (geojson | v5)NoSpecify the desired response format of results (geojson, default) or for backwards compatibility (v5).—
regionstringNoTop-level sub-national administrative features, such as states in the United States or provinces in Canada or China.—
streetstringNoThe name of the street in the address.—
countrystringNoLimit results to one or more countries. Permitted values are ISO 3166 alpha 2 country codes separated by commas.—
languagestringNoSet the language of the text supplied in responses. Also affects result scoring, with results matching the user's query in the requested language being preferred over results that match in another language. Options are IETF language tags comprised of a mandatory ISO 639-1 language code and, optionally, one or more IETF subtags for country or script. More than one value can also be specified, separated by commas.—
localitystringNoOfficial sub-city features present in countries where such an additional administrative layer is used in postal addressing.—
postcodestringNoPostal codes used in country-specific national addressing systems.—
entrancesbooleanNoSpecify whether to return building entrance data (true) or not (false, default). When set to true, building entrances associated with address features will be included in the response. This parameter is in Public Preview.—
permanentbooleanNoSpecify whether you intend to store the results of the query (true) or not (false, default).—
proximitystringNoBias the response to favor results that are closer to this location. Provided as two comma-separated coordinates in longitude,latitude order, or the string ip to bias based on reverse IP lookup.—
worldviewenum (ar | cn | in | jp | ma | rs | ru | tr | us)NoReturns features that are defined differently by audiences that belong to various regional, cultural, or political groups. Available worldviews are: ar, cn, in, jp, ma, rs, ru, tr, us. If worldview is not set, the us worldview boundaries are returned by default.—
autocompletebooleanNoSpecify whether to return autocomplete results (true, default) or not (false). When autocomplete is enabled, results will be included that start with the requested string, rather than responses that match it exactly.—
neighborhoodstringNoColloquial sub-city features often referred to in local parlance. Not available for reverse geocoding requests.—
address_line1stringNoA string including address_number and street. These values can be provided as separate parameters address_number and street.—
address_numberstringNoThe number associated with the house.—

Invocation example

Copy the request and explore its response example.

POST/agent-api/v1/tool/executeX-Api-Key
Request coderequest.sh
curl --request POST \
  --url 'https://agentearth.ai/agent-api/v1/tool/execute?tool_name=ae_mapbox_search_geocoding_get_forward' \
  --header "X-Api-Key: $AGENTEARTH_API_KEY" \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "params": {
    "q": "test"
  }
}'
Response exampleresponse.json
JSONPartial content
{
  "attribution": "NOTICE: © 2026 Mapbox and its suppliers. All rights reserved. Use of this data is subject to the Mapbox Terms of Service (https://www.mapbox.com/about/maps/). This response and the information it contains may not be retained.",
  "features": [
    {
      "geometry": {
        "coordinates": [
          9.448274
        ],
        "type": "Point"
      },
      "id": "dXJuOm1ieHBsYzpma2pp",
      "properties": {
        "bbox": [
          9.232804
        ],
        "context": {
          "country": {
            "country_code": "TN",
            "country_code_alpha_3": "TUN",
            "mapbox_id": "dXJuOm1ieHBsYzpJdUk",
            "name": "Tunisia",
            "wikidata_id": "Q948"
          },
          "place": {
            "mapbox_id": "dXJuOm1ieHBsYzpma2pp",
            "name": "تستور",
            "wikidata_id": "Q1250999"
          },
          "region": {
            "mapbox_id": "dXJuOm1ieHBsYzpBU1Rp",
            "name": "Béja",
            "region_code": "31",
            "region_code_full": "TN-31",
            "wikidata_id": "Q276576"
          }
        },
        "coordinates": {
          "latitude": 36.553764,
          "longitude": 9.448274
        },
        "feature_type": "place",
        "full_address": "تستور, Béja, Tunisia",
        "name": "Testour"
      },
      "type": "Feature"
    }
  ],
  "type": "FeatureCollection"
}

This example shows part of the response. Copied content is valid JSON.