Search location
POSThttps://api.foxentry.com/location/search
This enpoint mainly serves as autocomplete but can be used to search for specific addresses based on filter criteria as well. Foxentry will automatically offer you suggestions to complete the address you are writing down.
Pay attention to the client section in the request body. You can specify the user's location in order to receive more relevant suggestions.
Headers
Api-VersionstringAuthorizationstringrequiredBody params
requestobjectrequiredCustom ID assigned by you if you need so.
queryobjectrequiredParameters you want to validate or search for.
Type of search.
Searched value.
Street.
Street with number.
Full number.
First part of the number.
Second part of the number.
City.
ZIP code.
Federal state.
Region.
District.
Country code in format ISO-3166-1 alpha-2.
optionsobjectOptions that change how the endpoint behaves.
Limits number of results returned by the endpoint.Default
10Pagination offset. Available only if the resultsTotal in response is not null.Default
0If true, the results can contain streets without number. This might occur when the street is present in multiple cities. Applicable only when using the streetWithNumber or full search types.Default
truePrefer = prefer results matching the filter parameters, limit = limit to results matching the filter parameters.Default
limitIf true, values with different format would be accepted. (Uppercase and diacritics).Default
trueIf true, alternative values for filter types would be accepted. For example for City, also CityDistrict and CityDistrictSpecial would be accepted. (Praha, Praha 8, Karlín).Default
trueIf true, only exact match would be accepted. For example "Prah" would return 0 results, since no city with the exact name exists.Default
trueData scope of returned data.Default
basicArray of allowed data sources, which restricts countries the module searches. Although we use the request.client object to provide most relevant results, it is generally recommended to to limit this option to only the necessary sources - especially if you don't utilize the request.client object.Default
["AD", "AL", "AT", "BA", "BE", "BG", "CH", "CY", "CZ", "DE", "DK", "ES", "FR", "GB", "GR", "HR", "HU", "IS", "IT", "LI", "LU", "MC", "ME", "MK", "MT", "NL", "PL", "RO", "RS", "SI", "SK", "SM", "VA", "XK"]Whether to return locally formatted ZIP code or not. (130 00 vs 13000).Default
falseThis option determines the format in which the country is returned. Choices include local (Česká republika) and international (Czech republic) variants with their shortened counterparts (Česko, Czechia). You can use ISO 3166 alpha codes (CZ, CZE) as well.Default
alpha2This option determines the format in which the city is returned. Minimal = Praha, basic = Praha 8, extended = Praha 8 - Karlín.Default
basicclientobjectInformation about your user, to make results more relevant.
Country code in ISO-3166-1 alpha-2 format.
Client's latitude
Client's longitude
Empty fields use the example value shown in grey. Everything you type here is written into the request on the right, and the other way round.
Responses
Response body · application/json
statusintegerStatus of API response.
requestobjectendpointstringcodestringCode of request.
customIdstring | nullCustom ID assigned by you if you need so.
queryobjecttypestringType of search.
streetstreetWithNumbernumber.fullnumber.part1number.part2cityzipfullvaluestringSearched value.
filterobjectAdditional filter in order to specify the search results. You can for example set as a filter city of Prague, so the the search engine would look for the addresses only in Prague. Pay attention to the options, which determines how the filter should behave.
streetstring | nullStreet.
streetWithNumberstring | nullStreet with number.
number.fullstring | nullFull number.
number.part1string | nullFirst part of the number.
number.part2string | nullSecond part of the number.
citystring | nullCity.
zipstring | nullZIP code.
statestring | nullFederal state.
regionstring | nullRegion.
districtstring | nullDistrict.
countrystring | nullCountry code in format ISO-3166-1 alpha-2.
optionsobjectQuery options.
resultsLimitintegerLimits number of results returned by the endpoint.
resultsOffsetintegerPagination offset. Available only if the resultsTotal in response is not null.
allowPartialResultsbooleanIf true, the results can contain streets without number. This might occur when the street is present in multiple cities. Applicable only when using the streetWithNumber or full search types.
filterModestringPrefer = prefer results matching the filter parameters, limit = limit to results matching the filter parameters.
limitpreferfilterAcceptFormatbooleanIf true, values with different format would be accepted. (Uppercase and diacritics).
filterAcceptAlternativesbooleanIf true, alternative values for filter types would be accepted. For example for City, also CityDistrict and CityDistrictSpecial would be accepted. (Praha, Praha 8, Karlín).
filterExactMatchbooleanIf true, only exact match would be accepted. For example "Prah" would return 0 results, since no city with the exact name exists.
dataScopestringData scope of returned data.
basicfulldataSourcearray[string]Array of allowed data sources, which restricts countries the module searches. Although we use the request.client object to provide most relevant results, it is generally recommended to to limit this option to only the necessary sources - especially if you don't utilize the request.client object.
zipFormatbooleanWhether to return locally formatted ZIP code or not. (130 00 vs 13000).
countryFormatstringThis option determines the format in which the country is returned. Choices include local (Česká republika) and international (Czech republic) variants with their shortened counterparts (Česko, Czechia). You can use ISO 3166 alpha codes (CZ, CZE) as well.
alpha2alpha3locallocalShortenedinternationalinternationalShortenedcityFormatstringThis option determines the format in which the city is returned. Minimal = Praha, basic = Praha 8, extended = Praha 8 - Karlín.
minimalbasicextendedclientobjectAdditional information about your user (from whom you've obtained the data sent in query) to increase relevance of the results. If you do not wish to provide this information, you can limit results to relevant countries using the dataSource parameter present in some modules.
ipstringcountrystringCountry code in ISO-3166-1 alpha-2 format.
locationobjectLatitude & longitude of the client's approximate location.
latnumberClient's latitude
lonnumberClient's longitude
responseobjectLocationSearchResponse
resultsCountintegerNumber of results.
resultsOffsetintegerPagination offset
resultsTotalinteger | nullMaximum number of results that can be returned. Null if pagination not available.
resultsarray[object]dataobjectcountrystring | nullCountry code in format ISO-3166-1 alpha-2.
statestring | nullFederal state
regionstring | nulldistrictstring | nullcityDistrictstring | nullcityDistrictSpecialstring | nullSpecial types of city districts. Used only in Prague at the moment.
cityPartstring | nullcityAdministrativestring | nullCity Administrative area.
cadastralAreastring | nullCity cadastral area.
idsobjectAddress internal & external ids.
internalstring | nullInternal address ID.
externalstring | nullExternal address ID. May vary for every supported country. CZ = RUIAN, PL = Government data, SK = no external ID.
regionstring | nullRegion ID.
districtstring | nullDistrict ID.
cityDistrictSpecialstring | nullCity district special ID.
cityDistrictstring | nullCity district ID.
cityPartstring | nullCity part ID.
cadastralAreastring | nullCadastral area ID.
citystring | nullCity ID.
streetstring | nullStreet ID.
streetstring | nullStreet.
numberobject | nullpart1string | nullFirst section of house number.
part1Numberstring | nullNumerical part of the first section.
part1Letterstring | nullTextual part of the first section.
part2string | nullSecond section of house number.
part2Numberstring | nullNumerical part of the second section.
part2Letterstring | nullTextual part of the second section.
fullstring | nullFull house number.
typestring | nullType of house number.
streetWithNumberstring | nullStreet with number.
citystring | nullLocation city.
zipstring | nullZIP code.
postOfficeobjectIn what post office jurisdiction the address falls under.
namestring | nullgeometryobjectgpsobjectcustomarray[object]Custom coordinate system. May vary for every country.
fullstring | nullerrorsarray[string]List of errors related to the request. Should be empty if the request finished successfully.
Response body · application/json
statusintegerHTTP status of the response.
errorsarray[object]What went wrong.
groupstringError group.
REQUESTAUTHVALUESERVERtypestringError type.
subtypestring | nullMore specific error type.
severitystringHow serious the error is.
criticalwarninginforelatedToarray[string]Query parameters the error relates to.
descriptionstringHuman readable description.
Response body · application/json
statusintegerHTTP status of the response.
errorsarray[object]What went wrong.
groupstringError group.
REQUESTAUTHVALUESERVERtypestringError type.
subtypestring | nullMore specific error type.
severitystringHow serious the error is.
criticalwarninginforelatedToarray[string]Query parameters the error relates to.
descriptionstringHuman readable description.
Response body · application/json
statusintegerHTTP status of the response.
errorsarray[object]What went wrong.
groupstringError group.
REQUESTAUTHVALUESERVERtypestringError type.
subtypestring | nullMore specific error type.
severitystringHow serious the error is.
criticalwarninginforelatedToarray[string]Query parameters the error relates to.
descriptionstringHuman readable description.
Response body · application/json
statusintegerHTTP status of the response.
errorsarray[object]What went wrong.
groupstringError group.
REQUESTAUTHVALUESERVERtypestringError type.
subtypestring | nullMore specific error type.
severitystringHow serious the error is.
criticalwarninginforelatedToarray[string]Query parameters the error relates to.
descriptionstringHuman readable description.
Response body · application/json
statusintegerHTTP status of the response.
errorsarray[object]What went wrong.
groupstringError group.
REQUESTAUTHVALUESERVERtypestringError type.
subtypestring | nullMore specific error type.
severitystringHow serious the error is.
criticalwarninginforelatedToarray[string]Query parameters the error relates to.
descriptionstringHuman readable description.
Response body · application/json
statusintegerHTTP status of the response.
errorsarray[object]What went wrong.
groupstringError group.
REQUESTAUTHVALUESERVERtypestringError type.
subtypestring | nullMore specific error type.
severitystringHow serious the error is.
criticalwarninginforelatedToarray[string]Query parameters the error relates to.
descriptionstringHuman readable description.
Response body · application/json
statusintegerHTTP status of the response.
errorsarray[object]What went wrong.
groupstringError group.
REQUESTAUTHVALUESERVERtypestringError type.
subtypestring | nullMore specific error type.
severitystringHow serious the error is.
criticalwarninginforelatedToarray[string]Query parameters the error relates to.
descriptionstringHuman readable description.
Response body · application/json
statusintegerHTTP status of the response.
errorsarray[object]What went wrong.
groupstringError group.
REQUESTAUTHVALUESERVERtypestringError type.
subtypestring | nullMore specific error type.
severitystringHow serious the error is.
criticalwarninginforelatedToarray[string]Query parameters the error relates to.
descriptionstringHuman readable description.
Response body · application/json
statusintegerHTTP status of the response.
errorsarray[object]What went wrong.
groupstringError group.
REQUESTAUTHVALUESERVERtypestringError type.
subtypestring | nullMore specific error type.
severitystringHow serious the error is.
criticalwarninginforelatedToarray[string]Query parameters the error relates to.
descriptionstringHuman readable description.