---
title: Forward Geocoding API - Convert Address to Lat/Long Coordinates
version: 1.0.0
description: Convert a free-form address, place name, or point of interest into geographic coordinates. Returns up to 40 ranked matches per request, each with latitude/longitude, a structured address breakdown (street, city, state, country), a WGS84 bounding box, and any points of interest at that location. Use the `limit` parameter to control result count, the four `min_lat`/`max_lat`/`min_lon`/`max_lon` parameters together to bias results toward a geographic viewbox, and the `Accept-Language` header to localize result names. A query that matches nothing returns a `404` error rather than an empty array.
openapi: 3.1.1
servers:
  - https://api.apifreaks.com/v1.0
paths: 1
operations: 1
schemas: 4
---

## Table of Contents

- [Forward Geocoding API - Convert Address to Lat/Long Coordinates v1.0.0](#forward-geocoding-api-convert-address-to-latlong-coordinates-v100)
  - [Authentication](#authentication)
  - [Geocoder APIs](#geocoder-apis)
    - [forwardGeocode](#forwardgeocode)
      - [Parameters](#parameters)
      - [Responses](#responses)
  - [Schemas](#schemas)
    - [ErrorResponse](#errorresponse)
    - [ForwardGeocodeResponse](#forwardgeocoderesponse)
    - [GeocodeResponse](#geocoderesponse)
    - [PointOfInterest](#pointofinterest)



# Forward Geocoding API - Convert Address to Lat/Long Coordinates v1.0.0

Convert a free-form address, place name, or point of interest into geographic coordinates. Returns up to 40 ranked matches per request, each with latitude/longitude, a structured address breakdown (street, city, state, country), a WGS84 bounding box, and any points of interest at that location. Use the `limit` parameter to control result count, the four `min_lat`/`max_lat`/`min_lon`/`max_lon` parameters together to bias results toward a geographic viewbox, and the `Accept-Language` header to localize result names. A query that matches nothing returns a `404` error rather than an empty array.

Base URLs:

* [https://api.apifreaks.com/v1.0](https://api.apifreaks.com/v1.0)

## Authentication

* API Key (ApiKeyAuthHeader)
    - Parameter Name: **X-apiKey**, in: header. Pass your API key via the X-apiKey request header.

* API Key (ApiKeyAuthQuery)
    - Parameter Name: **apiKey**, in: query. Pass your API key via the apiKey query parameter.

## Geocoder APIs

### forwardGeocode

`GET /geocoder/search`

*Convert an address or place name into geographic coordinates*

Search for a free-form address, place name, or point of interest and return matching locations with coordinates, structured address components, and a bounding box.

#### Parameters

|Name|In|Type|Required|Description|
|---|---|---|---|---|
|query|query|string|true|Free-form search query, e.g. `Wembley Stadium, London`.|
|limit|query|integer|false|Maximum number of results to return. May return fewer if matches are weak.|
|min_lat|query|number(float)|false|Minimum latitude of the viewbox used to bias results. Must be provided together with `max_lat`, `min_lon`, and `max_lon`, and must be less than or equal to `max_lat`.|
|max_lat|query|number(float)|false|Maximum latitude of the viewbox used to bias results. Must be provided together with `min_lat`, `min_lon`, and `max_lon`, and must be greater than or equal to `min_lat`.|
|min_lon|query|number(float)|false|Minimum longitude of the viewbox used to bias results. Must be provided together with `min_lat`, `max_lat`, and `max_lon`, and must be less than or equal to `max_lon`.|
|max_lon|query|number(float)|false|Maximum longitude of the viewbox used to bias results. Must be provided together with `min_lat`, `max_lat`, and `min_lon`, and must be greater than or equal to `min_lon`.|
|Accept-Language|header|string|false|Preferred language order for result names, as a comma-separated list of language codes or a single code. Results are returned in the first matched language, falling back to `en` if none match.|

> Example responses

> Successful geocoding response

```json
[
  {
    "lat": 51.55606945,
    "lon": -0.27960339379401444,
    "name": "Wembley Stadium",
    "category": "tourism",
    "type": "attraction",
    "poi": [
      {
        "name": "Wembley Stadium",
        "category": "leisure",
        "type": "stadium"
      }
    ],
    "street": "Pacific Crescent",
    "area": "London Borough of Brent",
    "postcode": "HA9 0SL",
    "city": "Greater London",
    "state_code": "GB-ENG",
    "state": "England",
    "country_code": "GB",
    "country": "United Kingdom",
    "full_address": "Wembley Stadium, Pacific Crescent, London Borough of Brent, Greater London, England, HA9 0SL, United Kingdom",
    "bounding_box": [
      "51.5547925",
      "51.5573402",
      "-0.2817245",
      "-0.2774831"
    ]
  }
]
```

> Bad Request — Invalid or missing parameters

```json
{
  "error": "Invalid Param Exception",
  "message": "please pass correct parameters",
  "path": "/v1.0/geocoder/search",
  "status": 400,
  "timestamp": "2026-07-22T14:29:30.362Z"
}
```

```json
{
  "error": "Invalid Query Limit Provided",
  "message": "Please provide a valid limit. Valid range is from 1 to 40.",
  "path": "/v1.0/geocoder/search",
  "status": 400,
  "timestamp": "2026-07-22T14:29:30.894Z"
}
```

```json
{
  "error": "Invalid Viewbox Latitude",
  "message": "Minimum latitude cannot be greater than maximum latitude in the viewbox.",
  "path": "/v1.0/geocoder/search",
  "status": 400,
  "timestamp": "2026-07-22T14:30:11.104Z"
}
```

```json
{
  "error": "Invalid Viewbox Longitude",
  "message": "Minimum longitude cannot be greater than maximum longitude in the viewbox.",
  "path": "/v1.0/geocoder/search",
  "status": 400,
  "timestamp": "2026-07-22T14:30:11.104Z"
}
```

> Not Found — No results matched the query

```json
{
  "error": "No Result Found",
  "message": "No results found for the given query.",
  "path": "/v1.0/geocoder/search",
  "status": 404,
  "timestamp": "2026-07-22T14:29:58.349Z"
}
```

#### Responses

|Status|Meaning|Description|Schema|
|---|---|---|---|
|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|Successful geocoding response|[ForwardGeocodeResponse](#forwardgeocoderesponse)|
|400|[Bad Request](https://tools.ietf.org/html/rfc7231#section-6.5.1)|Bad Request — Invalid or missing parameters|[ErrorResponse](#errorresponse)|
|404|[Not Found](https://tools.ietf.org/html/rfc7231#section-6.5.4)|Not Found — No results matched the query|[ErrorResponse](#errorresponse)|

#### Response Headers

|Status|Header|Type|Format|Description|
|---|---|---|---|---|
|200|X-AF-Credits-Cost|integer||Specifies the number of credits consumed by the current request.|
|400|X-AF-Credits-Cost|integer||Specifies the number of credits consumed by the current request.|
|404|X-AF-Credits-Cost|integer||Specifies the number of credits consumed by the current request.|

To perform this operation, you must be authenticated by means of one of the following methods:
ApiKeyAuthHeader, ApiKeyAuthQuery

## Schemas

### ErrorResponse

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|error|string|false|none|Short error category or exception type.|
|message|string|true|none|Human-readable error message describing the failure.|
|path|string|false|none|API endpoint path that produced the error.|
|status|integer|false|none|HTTP status code returned with the error.|
|timestamp|string(date-time)|false|none|Timestamp when the error occurred (ISO 8601).|

### ForwardGeocodeResponse

Forward Geocoding Results

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|Forward Geocoding Results|[[GeocodeResponse](#geocoderesponse)]|false|none|List of locations matching the search query, one entry per match, up to the number requested via `limit`.|

### GeocodeResponse

A single geocoded location with coordinates and structured address components.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|lat|number(float)|true|none|WGS84 latitude value for the location.|
|lon|number(float)|true|none|WGS84 longitude value for the location.|
|name|string|false|none|Name for the primary place searched.|
|category|string|false|none|High-level category of the place, e.g. amenity, place, natural, building, highway.|
|type|string|false|none|Specific kind within the category, e.g. fast_food, city, park, residential, house_number.|
|poi|[[PointOfInterest](#pointofinterest)]|false|none|Points of interest at this location.|
|street|string|false|none|Street or road name.|
|area|string|false|none|Intra-city area below city level, e.g. suburb, borough, ward, district, tehsil, neighbourhood.|
|postcode|string|false|none|Postal code of the area.|
|city|string|false|none|Settlement label appropriate to the country, e.g. city, town, municipality.|
|county|string|false|none|Second-tier administrative area, e.g. county, district, prefecture.|
|state_code|string|false|none|Subdivision code, typically ISO-3166-2 (e.g. US-TX, PK-PB).|
|state|string|false|none|First-tier administrative area, e.g. state, region, province, division.|
|country_code|string|true|none|Two-letter country code in upper case, ISO-3166-1 alpha-2.|
|country|string|true|none|Country name of the searched place.|
|full_address|string|true|none|Single-line, human-readable address of the location.|
|bounding_box|[string]|true|none|Extent of the feature as `[lat_min, lat_max, lon_min, lon_max]` in WGS84 decimal degrees.|

### PointOfInterest

A point of interest located at or near a geocoded result.

#### Properties

|Name|Type|Required|Restrictions|Description|
|---|---|---|---|---|
|name|string|false|none|Name of the point of interest.|
|category|string|false|none|High-level category of the point of interest, e.g. amenity, place, natural, building, highway.|
|type|string|false|none|Specific kind within the category, e.g. fast_food, city, park, residential, house_number.|